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 :jQuery

Container of all the rendered script content
Type:
  • jQuery
Source:

BasicWidget :BasicWidget

Type:
Source:

NoteContextAwareWidget :NoteContextAwareWidget

Type:
Source:

RightPanelWidget :RightPanelWidget

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

currentNote :FNote

Note where the script is currently executing, i.e. the note where the currently executing source code is written.
Type:
Source:

dayjs :dayjs

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

originEntity :object|null

Entity whose event triggered this execution.
Type:
  • object | null
Source:

startNote :FNote

Note where the script started executing, i.e., the (event) entrypoint of the current script execution.
Type:
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
title string
action function callback handling the click on the button
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.
icon string <optional>
 name of the boxicon to be used (e.g. "time" for "bx-time" icon)
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
title= string <optional>
 custom link tile with note's title as default
Source:
Returns:
- jQuery element with the link (wrapped in )
Type
jQuery

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

getActiveContext() → {NoteContext}

Source:
Returns:
- returns active context (split)
Type
NoteContext

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 center 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>

getActiveMainContext() → {NoteContext}

Source:
Returns:
- returns active main context (first split in a tab, represents the tab as a whole)
Type
NoteContext

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

getMainNoteContexts() → {Array.<NoteContext>}

Source:
Returns:
- returns all main contexts representing tabs
Type
Array.<NoteContext>

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>

getNoteContexts() → {Array.<NoteContext>}

Source:
Returns:
- returns all note contexts (splits) in all tabs
Type
Array.<NoteContext>

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:

runAsyncOnBackendWithManualTransactionHandling(func, params) → {Promise.<*>}

Executes given anonymous function on the backend. Internally this serializes the anonymous function into string and sends it to backend via AJAX. This function is meant for advanced needs where an async function is necessary. In this case, the automatic request-scoped transaction management is not applied, and you need to manually define transaction via api.transactional(). If you have a synchronous function, please use api.runOnBackend().
Parameters:
Name Type Description
func function | string (synchronous) function 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.<*>

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

Executes given anonymous function on the backend. Internally this serializes the anonymous function into string and sends it to backend via AJAX. Please make sure that the supplied function is synchronous. Only sync functions will work correctly with transaction management. If you really know what you're doing, you can call api.runAsyncOnBackendWithManualTransactionHandling()
Parameters:
Name Type Description
func function | string (synchronous) function 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://triliumnext.github.io/Docs/Wiki/search.html
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://triliumnext.github.io/Docs/Wiki/search.html
Parameters:
Name Type Description
searchString string
Source:
Returns:
Type
Promise.<Array.<FNote>>

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

Hoist note in the current tab. See https://triliumnext.github.io/Docs/Wiki/note-hoisting.html
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>

showConfirmDialog(message) → {Promise.<boolean>}

Show confirm dialog to the user.
Parameters:
Name Type Description
message string
Source:
Returns:
promise resolving to true if the user confirmed
Type
Promise.<boolean>

showError(message)

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

showInfoDialog(message) → {Promise}

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

showMessage(message)

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

showPromptDialog(props) → {Promise.<string>}

Show prompt dialog to the user.
Parameters:
Name Type Description
props object
Properties
Name Type Description
title string
message string
defaultValue string
Source:
Returns:
promise resolving to the answer provided by the user
Type
Promise.<string>

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>