# 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:
  - services/frontend_script_api.js, line 37

### Members

#### $container :jQuery

Container of all the rendered script content

##### Type:

- jQuery

Source:
  - services/frontend_script_api.js, line 42

#### BasicWidget :BasicWidget

##### Type:

- BasicWidget

Source:
  - services/frontend_script_api.js, line 77

#### NoteContextAwareWidget :NoteContextAwareWidget

##### Type:

- NoteContextAwareWidget

Source:
  - services/frontend_script_api.js, line 74

#### RightPanelWidget :RightPanelWidget

##### Type:

- RightPanelWidget

Source:
  - services/frontend_script_api.js, line 71

#### createNoteLink

Deprecated:
  - - use api.createLink() instead
Source:
  - services/frontend_script_api.js, line 407

#### currentNote :FNote

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

##### Type:

- FNote

Source:
  - services/frontend_script_api.js, line 54

#### dayjs :dayjs

day.js library for date manipulation. See https://day.js.org for documentation

##### Type:

- dayjs

Source:
  - services/frontend_script_api.js, line 68
See:
  - https://day.js.org

#### originEntity :object|null

Entity whose event triggered this execution.

##### Type:

- object | null

Source:
  - services/frontend_script_api.js, line 60

#### startNote :FNote

Note where the script started executing, i.e., the (event) entrypoint of the current script execution.

##### Type:

- FNote

Source:
  - services/frontend_script_api.js, line 48

### 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:
  - services/frontend_script_api.js, line 96

##### 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:
  - services/frontend_script_api.js, line 86

##### 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:
  - services/frontend_script_api.js, line 156

#### 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:
  - services/frontend_script_api.js, line 415

#### 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:
  - services/frontend_script_api.js, line 581

##### Returns:

Type
  Promise.<void>

#### createLink(notePath, paramsopt) → {jQuery}

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:
  - services/frontend_script_api.js, line 404

##### Returns:

- jQuery element with the link (wrapped in )

Type
  jQuery

#### formatDateISO(date) → {string}

##### Parameters:

Name | Type | Description
--- | --- | ---
`date` | Date |

Source:
  - services/frontend_script_api.js, line 318

##### 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:
  - services/frontend_script_api.js, line 625

##### Returns:

formatted string

Type
  string

#### formatSize(size) → {string}

##### Parameters:

Name | Type | Description
--- | --- | ---
`size` | int | in bytes

Source:
  - services/frontend_script_api.js, line 617

##### Returns:

formatted string

Type
  string

#### getActiveContext() → {NoteContext}

Source:
  - services/frontend_script_api.js, line 427

##### Returns:

- returns active context (split)

Type
  NoteContext

#### getActiveContextCodeEditor() → {Promise.<CodeMirror>}

See https://codemirror.net/doc/manual.html#api

Source:
  - services/frontend_script_api.js, line 461

##### Returns:

instance of CodeMirror

Type
  Promise.<CodeMirror>

#### getActiveContextNote() → {FNote}

Source:
  - services/frontend_script_api.js, line 421

##### Returns:

active note (loaded into center pane)

Type
  FNote

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

Source:
  - services/frontend_script_api.js, line 476

##### 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:
  - services/frontend_script_api.js, line 453

##### Returns:

instance of CKEditor

Type
  Promise.<BalloonEditor>

#### getActiveMainContext() → {NoteContext}

Source:
  - services/frontend_script_api.js, line 433

##### 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:
  - services/frontend_script_api.js, line 470

##### 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:
  - services/frontend_script_api.js, line 485

##### 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:
  - services/frontend_script_api.js, line 529

##### 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:
  - services/frontend_script_api.js, line 311

##### Returns:

Type
  string

#### getMainNoteContexts() → {Array.<NoteContext>}

Source:
  - services/frontend_script_api.js, line 445

##### 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:
  - services/frontend_script_api.js, line 547

##### 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:
  - services/frontend_script_api.js, line 281

##### Returns:

Type
  Promise.<FNote>

#### getNoteContexts() → {Array.<NoteContext>}

Source:
  - services/frontend_script_api.js, line 439

##### 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:
  - services/frontend_script_api.js, line 294

##### Returns:

Type
  Promise.<Array.<FNote>>

#### getTodayNote() → {Promise.<FNote>}

Returns date-note for today. If it doesn't exist, it is automatically created.

Source:
  - services/frontend_script_api.js, line 520

##### 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:
  - services/frontend_script_api.js, line 538

##### 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:
  - services/frontend_script_api.js, line 556

##### Returns:

Type
  Promise.<FNote>

#### log(message) → {void}

Log given message to the log pane in UI

##### Parameters:

Name | Type | Description
--- | --- | ---
`message` |  |

Source:
  - services/frontend_script_api.js, line 636

##### 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:
  - services/frontend_script_api.js, line 129

##### 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:
  - services/frontend_script_api.js, line 111

##### Returns:

Type
  Promise.<void>

#### parseDate(str) → {Date}

##### Parameters:

Name | Type | Description
--- | --- | ---
`str` | string |

Source:
  - services/frontend_script_api.js, line 325

##### 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:
  - services/frontend_script_api.js, line 500

##### 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:
  - services/frontend_script_api.js, line 510

##### 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:
  - services/frontend_script_api.js, line 610

##### 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:
  - services/frontend_script_api.js, line 601

##### Returns:

Type
  Promise.<void>

#### reloadNotes(noteIds)

Update frontend tree (note) cache from the backend.

##### Parameters:

Name | Type | Description
--- | --- | ---
`noteIds` | Array.<string> |

Source:
  - services/frontend_script_api.js, line 302

#### 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:
  - services/frontend_script_api.js, line 240

##### 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:
  - services/frontend_script_api.js, line 218

##### 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:
  - services/frontend_script_api.js, line 268

##### 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:
  - services/frontend_script_api.js, line 256

##### 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:
  - services/frontend_script_api.js, line 565

##### Returns:

Type
  Promise.<void>

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`$el` | object | jquery object on which to set up the tooltip

Source:
  - services/frontend_script_api.js, line 492

##### Returns:

Type
  Promise.<void>

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

Show confirm dialog to the user.

##### Parameters:

Name | Type | Description
--- | --- | ---
`message` | string |

Source:
  - services/frontend_script_api.js, line 359

##### 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:
  - services/frontend_script_api.js, line 341

#### showInfoDialog(message) → {Promise}

Show an info dialog to the user.

##### Parameters:

Name | Type | Description
--- | --- | ---
`message` | string |

Source:
  - services/frontend_script_api.js, line 350

##### Returns:

Type
  Promise

#### showMessage(message)

Show an info toast message to the user.

##### Parameters:

Name | Type | Description
--- | --- | ---
`message` | string |

Source:
  - services/frontend_script_api.js, line 333

#### 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:
  - services/frontend_script_api.js, line 371

##### 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:
  - services/frontend_script_api.js, line 380

#### 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:
  - services/frontend_script_api.js, line 389

#### 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:
  - services/frontend_script_api.js, line 593

##### Returns:

Type
  Promise.<void>