Class: FrontendScriptApi

FrontendScriptApi()

new FrontendScriptApi()

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

Source:

Members

$container

Properties:
Name Type Description
container jQuery of all the rendered script content
Source:

BasicWidget

Properties:
Type Description
BasicWidget
Source:

NoteContextAwareWidget

Properties:
Type Description
NoteContextAwareWidget
Source:

RightPanelWidget

Properties:
Type Description
RightPanelWidget
Source:
Deprecated:
  • - use api.createLink() instead
Source:

currentNote

Properties:
Name Type Description
note object where the script is currently executing
Source:

dayjs

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

originEntity

Properties:
Name Type Description
entity object | null whose event triggered this execution
Source:

startNote

Properties:
Name Type Description
note object where the script started executing
Source:

Methods

activateNewNote(notePath) → {Promise.<void>}

Activates newly created note. Compared to this.activateNote() also makes sure that frontend has been fully synced.
Parameters:
Name Type Description
notePath string (or noteId)
Source:
Returns:
Type
Promise.<void>

activateNote(notePath) → {Promise.<void>}

Activates note in the tree and in the note detail.
Parameters:
Name Type Description
notePath string (or noteId)
Source:
Returns:
Type
Promise.<void>

addButtonToToolbar(opts)

Adds 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 Description
opts.id string <optional>
 id of the button, used to identify the old instances of this button to be replaced ID is optional because of BC, but not specifying it is deprecated. ID can be alphanumeric only.
opts.title string
opts.icon string <optional>
 name of the boxicon to be used (e.g. "time" for "bx-time" icon)
opts.action function callback handling the click on the button
opts.shortcut string <optional>
 keyboard shortcut for the button, e.g. "alt+t"
Deprecated:
  • you can now create/modify launchers in the top-left Menu -> Configure Launchbar for special needs there's also backend API's createOrUpdateLauncher()
Source:

addTextToActiveContextEditor(text)

Adds given text to the editor cursor
Parameters:
Name Type Description
text string this must be clear text, HTML is not supported.
Source:

bindGlobalShortcut(keyboardShortcut, handler, namespaceopt) → {Promise.<void>}

Parameters:
Name Type Attributes Description
keyboardShortcut string e.g. "ctrl+shift+a"
handler function
namespace string <optional>
 specify namespace of the handler for the cases where call for bind may be repeated. If a handler with this ID exists, it's replaced by the new handler.
Source:
Returns:
Type
Promise.<void>
Create a note link (jQuery object) for given note.
Parameters:
Name Type Attributes Description
notePath string (or noteId)
params object <optional>
Properties
Name Type Attributes Default Description
showTooltip boolean <optional>
 true enable/disable tooltip on the link
showNotePath boolean <optional>
 false show also whole note's path as part of the link
showNoteIcon boolean <optional>
 false show also note icon before the title
title= string <optional>
 custom link tile with note's title as default
Source:

formatDateISO(date) → {string}

Parameters:
Name Type Description
date Date
Source:
Returns:
date in YYYY-MM-DD format
Type
string

formatNoteSize(size) → {string}

Parameters:
Name Type Description
size int in bytes
Deprecated:
  • - use api.formatSize()
Source:
Returns:
formatted string
Type
string

formatSize(size) → {string}

Parameters:
Name Type Description
size int in bytes
Source:
Returns:
formatted string
Type
string

getActiveContextCodeEditor() → {Promise.<CodeMirror>}

See https://codemirror.net/doc/manual.html#api
Source:
Returns:
instance of CodeMirror
Type
Promise.<CodeMirror>

getActiveContextNote() → {FNote}

Source:
Returns:
active note (loaded into right pane)
Type
FNote

getActiveContextNotePath() → {Promise.<(string|null)>}

Source:
Returns:
returns a note path of active note or null if there isn't active note
Type
Promise.<(string|null)>

getActiveContextTextEditor() → {Promise.<BalloonEditor>}

See https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editor-Editor.html for documentation on the returned instance.
Source:
Returns:
instance of CKEditor
Type
Promise.<BalloonEditor>

getActiveNoteDetailWidget() → {Promise.<NoteDetailWidget>}

Get access to the widget handling note detail. Methods like `getWidgetType()` and `getTypeWidget()` to get to the implementation of actual widget type.
Source:
Returns:
Type
Promise.<NoteDetailWidget>

getComponentByEl(el) → {Component}

Returns component which owns the given DOM element (the nearest parent component in DOM tree)
Parameters:
Name Type Description
el Element DOM element
Source:
Returns:
Type
Component

getDayNote(date) → {Promise.<FNote>}

Returns day note for a given date. If it doesn't exist, it is automatically created.
Parameters:
Name Type Description
date string e.g. "2019-04-29"
Source:
Returns:
Type
Promise.<FNote>

getInstanceName() → {string}

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

getMonthNote(month) → {Promise.<FNote>}

Returns month-note. If it doesn't exist, it is automatically created.
Parameters:
Name Type Description
month string e.g. "2019-04"
Source:
Returns:
Type
Promise.<FNote>

getNote(noteId) → {Promise.<FNote>}

Returns note by given noteId. If note is missing from the cache, it's loaded. *
Parameters:
Name Type Description
noteId string
Source:
Returns:
Type
Promise.<FNote>

getNotes(noteIds, silentNotFoundErroropt) → {Promise.<Array.<FNote>>}

Returns list of notes. If note is missing from the 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. createLink())
Parameters:
Name Type Attributes Description
noteIds Array.<string>
silentNotFoundError boolean <optional>
 don't report error if the note is not found
Source:
Returns:
Type
Promise.<Array.<FNote>>

getTodayNote() → {Promise.<FNote>}

Returns date-note for today. If it doesn't exist, it is automatically created.
Source:
Returns:
Type
Promise.<FNote>

getWeekNote(date) → {Promise.<FNote>}

Returns day note for the first date of the week of the given date. If it doesn't exist, it is automatically created.
Parameters:
Name Type Description
date string e.g. "2019-04-29"
Source:
Returns:
Type
Promise.<FNote>

getYearNote(year) → {Promise.<FNote>}

Returns year-note. If it doesn't exist, it is automatically created.
Parameters:
Name Type Description
year string e.g. "2019"
Source:
Returns:
Type
Promise.<FNote>

log(message) → {void}

Log given message to the log pane in UI
Parameters:
Name Type Description
message
Source:
Returns:
Type
void

openSplitWithNote(notePath, activate) → {Promise.<void>}

Open a note in a new split.
Parameters:
Name Type Description
notePath string (or noteId)
activate boolean set to true to activate the new split, false to stay on the current split
Source:
Returns:
Type
Promise.<void>

openTabWithNote(notePath, activate) → {Promise.<void>}

Open a note in a new tab.
Parameters:
Name Type Description
notePath string (or noteId)
activate boolean set to true to activate the new tab, false to stay on the current tab
Source:
Returns:
Type
Promise.<void>

parseDate(str) → {Date}

Parameters:
Name Type Description
str string
Source:
Returns:
parsed object
Type
Date

protectNote(noteId, protect) → {Promise.<void>}

Parameters:
Name Type Description
noteId string
protect boolean true to protect note, false to unprotect
Source:
Returns:
Type
Promise.<void>

protectSubTree(noteId, protect) → {Promise.<void>}

Parameters:
Name Type Description
noteId string
protect boolean true to protect subtree, false to unprotect
Source:
Returns:
Type
Promise.<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

refreshIncludedNote(includedNoteId) → {Promise.<void>}

This will refresh all currently opened notes which have included note specified in the parameter
Parameters:
Name Type Description
includedNoteId noteId of the included note
Source:
Returns:
Type
Promise.<void>

reloadNotes(noteIds)

Update frontend tree (note) cache from the backend.
Parameters:
Name Type Description
noteIds Array.<string>
Source:

runOnBackend(script, params) → {Promise.<*>}

Executes given anonymous function on the backend. Internally this serializes the anonymous function into string and sends it to backend via AJAX.
Parameters:
Name Type Description
script string script to be executed on the backend
params Array.<?> list of parameters to the anonymous function to be sent to backend
Source:
Returns:
return value of the executed function on the backend
Type
Promise.<*>

searchForNote(searchString) → {Promise.<(FNote|null)>}

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
Parameters:
Name Type Description
searchString string
Source:
Returns:
Type
Promise.<(FNote|null)>

searchForNotes(searchString) → {Promise.<Array.<FNote>>}

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
Parameters:
Name Type Description
searchString string
Source:
Returns:
Type
Promise.<Array.<FNote>>

setHoistedNoteId(noteId) → {Promise.<void>}

Hoist note in the current tab. See https://github.com/zadam/trilium/wiki/Note-hoisting
Parameters:
Name Type Description
noteId string set hoisted note. 'root' will effectively unhoist
Source:
Returns:
Type
Promise.<void>

setupElementTooltip($el) → {Promise.<void>}

Parameters:
Name Type Description
$el object jquery object on which to set up the tooltip
Source:
Returns:
Type
Promise.<void>

showError(message)

Show an error message to the user.
Parameters:
Name Type Description
message string
Source:

showMessage(message)

Show an info message to the user.
Parameters:
Name Type Description
message string
Source:

triggerCommand(name, data)

Trigger command. This is a very low-level API which should be avoided if possible.
Parameters:
Name Type Description
name string
data object
Source:

triggerEvent(name, data)

Trigger event. This is a very low-level API which should be avoided if possible.
Parameters:
Name Type Description
name string
data object
Source:

waitUntilSynced() → {Promise.<void>}

Trilium runs in a backend and frontend process, when something is changed on the backend from a 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 a new note has been created, we should wait until it is synced into frontend and only then activate it.
Source:
Returns:
Type
Promise.<void>