# 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 24

### Members

#### $container

##### Properties:

Name | Type | Description
--- | --- | ---
`container` | jQuery | of all the rendered script content

Source:
  - services/frontend_script_api.js, line 26

#### BasicWidget

##### Properties:

Type | Description
--- | ---
BasicWidget |

Source:
  - services/frontend_script_api.js, line 45

#### NoteContextAwareWidget

##### Properties:

Type | Description
--- | ---
NoteContextAwareWidget |

Source:
  - services/frontend_script_api.js, line 42

#### RightPanelWidget

##### Properties:

Type | Description
--- | ---
RightPanelWidget |

Source:
  - services/frontend_script_api.js, line 39

#### createNoteLink

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

#### currentNote

##### Properties:

Name | Type | Description
--- | --- | ---
`note` | object | where the script is currently executing

Source:
  - services/frontend_script_api.js, line 31

#### dayjs

##### Properties:

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

Source:
  - services/frontend_script_api.js, line 36

#### originEntity

##### Properties:

Name | Type | Description
--- | --- | ---
`entity` | object | null | whose event triggered this execution

Source:
  - services/frontend_script_api.js, line 33

#### startNote

##### Properties:

Name | Type | Description
--- | --- | ---
`note` | object | where the script started executing

Source:
  - services/frontend_script_api.js, line 29

### 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 64

##### 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 54

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

#### 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 316

#### 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 458

##### Returns:

Type
  Promise.<void>

#### createLink(notePath, paramsopt)

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

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

##### Parameters:

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

Source:
  - services/frontend_script_api.js, line 251

##### 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 502

##### Returns:

formatted string

Type
  string

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

##### Parameters:

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

Source:
  - services/frontend_script_api.js, line 494

##### Returns:

formatted string

Type
  string

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

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

Source:
  - services/frontend_script_api.js, line 338

##### Returns:

instance of CodeMirror

Type
  Promise.<CodeMirror>

#### getActiveContextNote() → {FNote}

Source:
  - services/frontend_script_api.js, line 322

##### Returns:

active note (loaded into right pane)

Type
  FNote

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

Source:
  - services/frontend_script_api.js, line 353

##### 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 330

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

##### 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 362

##### 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 406

##### 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 244

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

##### 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 214

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

##### 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 397

##### 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 415

##### 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 433

##### 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 513

##### 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 97

##### 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 79

##### Returns:

Type
  Promise.<void>

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

##### Parameters:

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

Source:
  - services/frontend_script_api.js, line 258

##### 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 377

##### 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 387

##### 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 487

##### 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 478

##### 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 235

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

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

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

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

##### 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 369

##### Returns:

Type
  Promise.<void>

#### showError(message)

Show an error message to the user.

##### Parameters:

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

Source:
  - services/frontend_script_api.js, line 274

#### showMessage(message)

Show an info message to the user.

##### Parameters:

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

Source:
  - services/frontend_script_api.js, line 266

#### 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 283

#### 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 292

#### 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 470

##### Returns:

Type
  Promise.<void>