# Hooks

# onNoteStored

# Method call and parameters

/**
 * This function is called when a note gets stored to disk
 * You cannot modify stored notes, that would be a mess since
 * you are most likely editing them by hand at the same time
 *
 * @param {NoteApi} note - the note object of the stored note
 */
function onNoteStored(note);

1
2
3
4
5
6
7
8

You may want to take a look at the example on-note-opened.qml (opens new window).

# noteOpenedHook

# Method call and parameters

/**
 * This function is called after a note was opened
 *
 * @param {NoteApi} note - the note object that was opened
 */
function noteOpenedHook(note);

1
2
3
4
5
6

You may want to take a look at the example on-note-opened.qml (opens new window).

# noteDoubleClickedHook

# Method call and parameters

/**
 * This function is called after a note was double clicked
 *
 * @param {NoteApi} note - the note object that was clicked
 */
function noteDoubleClickedHook(note);

1
2
3
4
5
6

You may want to take a look at the example external-note-open.qml (opens new window).

# insertMediaHook

This function is called when a media file is inserted into the current note.

If this function is defined in multiple scripts, then the first script that returns a non-empty string wins.

# Method call and parameters

/**
 * @param fileName string the file path of the source media file before it was copied to the media folder
 * @param markdownText string the markdown text of the media file, e.g. ![my-image](media/my-image-4101461585.jpg)
 * @return string the new markdown text of the media file
 */
function insertMediaHook(fileName, markdownText);

1
2
3
4
5
6

You may want to take a look at the example example.qml (opens new window).

# insertAttachmentHook

This function is called when an attachment file is inserted into the current note.

If this function is defined in multiple scripts, then the first script that returns a non-empty string wins.

# Method call and parameters

/**
 * @param fileName string the file path of the source attachment file before it was copied to the attachment folder
 * @param markdownText string the markdown text of the attachment file, e.g. [my-file.txt](attachments/my-file-4245650967.txt)
 * @return string the new markdown text of the attachment file
 */
function insertAttachmentHook(fileName, markdownText);

1
2
3
4
5
6

You may want to take a look at the example example.qml (opens new window).

# insertingFromMimeDataHook

# Method call and parameters

/**
 * This function is called when html or a media file is pasted to a note with `Ctrl + Shift + V`
 *
 * @param text text of the QMimeData object
 * @param html html of the QMimeData object
 * @returns the string that should be inserted instead of the text from the QMimeData object
 */
function insertingFromMimeDataHook(text, html);

1
2
3
4
5
6
7
8

You may want to take a look at the example example.qml (opens new window), insert-headline-with-link-from-github-url.qml (opens new window) or note-text-from-5pm-mail.qml (opens new window).

# handleNoteTextFileNameHook

# Method call and parameters

/**
 * This function is called when a note gets stored to disk if
 * "Allow note file name to be different from headline" is enabled
 * in the settings
 *
 * It allows you to modify the name of the note file
 * Keep in mind that you have to care about duplicate names yourself!
 *
 * Return an empty string if the file name of the note should
 * not be modified
 *
 * @param {NoteApi} note - the note object of the stored note
 * @return {string} the file name of the note
 */
function handleNoteTextFileNameHook(note);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

You may want to take a look at the example example.qml (opens new window) or use-tag-names-in-filename.qml (opens new window).

# handleNoteNameHook

# Method call and parameters

/**
 * This function is called when the note name is determined for a note
 *
 * It allows you to modify the name of the note that is viewed
 *
 * Return an empty string if the name of the note should not be modified
 *
 * @param {NoteApi} note - the note object of the stored note
 * @return {string} the name of the note
 */
function handleNoteNameHook(note);

1
2
3
4
5
6
7
8
9
10
11

You may want to take a look at the example example.qml (opens new window).

It may not be a good idea to use this hook if the setting to use the file name as note name is active.

# handleNewNoteHeadlineHook

# Method call and parameters

/**
 * This function is called before a note is created
 *
 * It allows you to modify the headline of the note before it is created
 * Note that you have to take care about a unique note name, otherwise
 * the new note will not be created, it will just be found in the note list
 *
 * You can use this function for creating note templates
 *
 * @param headline text that would be used to create the headline
 * @return {string} the headline of the note
 */
function handleNewNoteHeadlineHook(headline);

1
2
3
4
5
6
7
8
9
10
11
12
13

You may want to take a look at the example custom-new-note-headline.qml (opens new window).

# preNoteToMarkdownHtmlHook

# Method call and parameters

/**
 * This function is called before the markdown html of a note is generated
 *
 * It allows you to modify what is passed to the markdown to html converter
 *
 * The function can for example be used in multiple scripts to render code (like LaTeX math or mermaid)
 * to its graphical representation for the preview
 *
 * The note will not be changed in this process
 *
 * @param {NoteApi} note - the note object
 * @param {string} markdown - the markdown that is about to being converted to html
 * @param {bool} forExport - true if the html is used for an export, false for the preview
 * @return {string} the modified markdown or an empty string if nothing should be modified
 */
function preNoteToMarkdownHtmlHook(note, markdown, forExport);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

You may want to take a look at the example preview-styling.qml (opens new window).

# noteToMarkdownHtmlHook

# Method call and parameters

/**
 * This function is called when the markdown html of a note is generated
 *
 * It allows you to modify this html
 * This is for example called before by the note preview
 *
 * The function can be used in multiple scripts to modify the html of the preview
 *
 * @param {NoteApi} note - the note object
 * @param {string} html - the html that is about to being rendered
 * @param {bool} forExport - true if the html is used for an export, false for the preview
 * @return {string} the modified html or an empty string if nothing should be modified
 */
function noteToMarkdownHtmlHook(note, html, forExport);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

You may want to take a look at the example example.qml (opens new window) or preview-styling.qml (opens new window).

Please refer to the Supported HTML Subset (opens new window) documentation for a list of all supported css styles.

# encryptionHook

# Method call and parameters

/**
 * This function is called when text has to be encrypted or decrypted
 *
 * @param text string the text to encrypt or decrypt
 * @param password string the password
 * @param decrypt bool if false encryption is demanded, if true decryption is demanded
 * @return the encrypted decrypted text
 */
function encryptionHook(text, password, decrypt);

1
2
3
4
5
6
7
8
9

You may want to take a look at the example encryption-keybase.qml (opens new window), encryption-pgp.qml (opens new window) or encryption-rot13.qml (opens new window).

# noteTaggingHook

You can implement your own note tagging mechanism for example with special text in your note like @tag1, @tag2, @tag3.

# Method call and parameters

/**
 * Handles note tagging for a note
 *
 * This function is called when tags are added to, removed from or renamed in
 * a note or the tags of a note should be listed
 *
 * @param note
 * @param action can be "add", "remove", "rename" or "list"
 * @param tagName tag name to be added, removed or renamed
 * @param newTagName tag name to be renamed to if action = "rename"
 * @return note text string or string-list of tag names (if action = "list")
 */
function noteTaggingHook(note, action, tagName, newTagName);

1
2
3
4
5
6
7
8
9
10
11
12
13

as soon as a script is activated that implements the new function noteTaggingHook note tagging will be handled by that function
following features should work via the QOwnNotes user interface
- initially importing tags like @tag from your notes and overwriting your current tag assignment
  - you will not lose your tags tree, just the former assignment to notes
  - you can still move tags into other tags
  - if more than one tag has the same name in your tag tree the first hit will be assigned
- adding a tag to a note will add the tag to the note text
- removing a tag from a note will remove the tag from the note text
- removing of tags in the tag list will remove those tags from your notes
- renaming of tags in the tag list will rename those tags in your notes
- bulk tagging of notes in the note list will add those tags to your notes
- bulk removing of tags from notes in the note list will remove those tags from your notes
- the application will trigger a series of add and remove actions for all selected tags and their children on all notes if tags are moved in the tag panel

You may want to take a look at the example note-tagging.qml (opens new window) to implement your own tagging mechanism.

WARNING

Make sure your list action is really fast, because it will be executed for every note every time the note folder is reloaded!

# noteTaggingByObjectHook

Similarly to noteTaggingHook you can implement your own note tagging mechanism, but you are not bound to tag names in the tag tree root. This way you can make use of the whole tag tree instead of only a tag list.

With noteTaggingByObjectHook you get a TagApi object as parameter, instead of a tag name. And as result for the list action you need to provide a list of tag ids.

This also means you need to create missing tags yourself to be able to provide a list of already existing tag ids for the list action.

# Method call and parameters

/**
 * Handles note tagging for a note
 *
 * This function is called when tags are added to, removed from or renamed in
 * a note or the tags of a note should be listed
 *
 * @param note
 * @param action can be "add", "remove", "rename" or "list"
 * @param tag to be added, removed or renamed
 * @param newTagName tag name to be renamed to if action = "rename"
 * @return note text string or string-list of tag ids (if action = "list")
 */
function noteTaggingByObjectHook(note, action, tag, newTagName);

1
2
3
4
5
6
7
8
9
10
11
12
13

You may want to take a look at the example note-tagging-by-object.qml (opens new window) to implement your own tagging mechanism.

# autocompletionHook

You can return a list of strings to be added to the autocompletion list when the autocompletion is invoked (for example by pressing Ctrl + Space).

# Method call and parameters

/**
 * Calls the autocompletionHook function for all script components
 * This function is called when autocompletion is invoked in a note
 *
 * @return QStringList of text for the autocomplete list
 */
function callAutocompletionHook();

1
2
3
4
5
6
7

You may want to take a look at the example autocompletion.qml (opens new window).

# websocketRawDataHook

This hook is called when data is sent from the QOwnNotes Web Companion browser extension via the web browser's context menu.

# Method call and parameters

/**
 * @param requestType can be "page" or "selection"
 * @param pageUrl the url of the webpage where the request was made
 * @param pageTitle the page title of the webpage where the request was made
 * @param rawData the data that was transmitted, html for requestType "page" or plain text for requestType "selection"
 * @param screenshotDataUrl the data url of the screenshot of the webpage where the request was made
 * @return true if data was handled by a hook
 */
function callHandleWebsocketRawDataHook(requestType, pageUrl, pageTitle, rawData, screenshotDataUrl);

1
2
3
4
5
6
7
8
9

You may want to take a look at the examples websocket-raw-data-new-note.qml (opens new window) and websocket-raw-data-selection-in-note.qml (opens new window).

# onDetachedProcessCallback

This hook is called when a script thread of startDetachedProcess is done executing.

# Method call and parameters

/**
 * This function is called when a script thread is done executing.
 * Hint: thread[1]==0 helps to determine if a bulk of started processes for a certain identifier is done.
 *
 * @param {QString} callbackIdentifier - the provided id when calling startDetachedProcess()
 * @param {QString} resultSet - the result of the process
 * @param {QVariantList} cmd - the entire command array [0-executablePath, 1-parameters, 2-exitCode]
 * @param {QVariantList} thread - the thread information array [0-passed callbackParameter, 1-remaining threads for this identifier]
 */
function onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread);

1
2
3
4
5
6
7
8
9
10

You may want to take a look at the example callback-example.qml (opens new window).

# windowStateChangedHook

# Method call and parameters

/**
 * This function is called after a WindowStateChange event was triggered
 *
 * @param {QString} windowState - the new window state, parameter value can be "minimized", "maximized", "fullscreen", "active" or "nostate"
 */
function windowStateChangedHook(windowState);

1
2
3
4
5
6

You may want to take a look at the example window-state-changed.qml (opens new window).

# workspaceSwitchedHook

This hook is called when workspaces are switched.

# Method call and parameters

/**
 * This function is called when workspaces are switched
 *
 * @param oldUuid old uuid of workspace
 * @param newUuid new uuid of workspace
 */
function workspaceSwitchedHook(oldUuid, newUuid);

1
2
3
4
5
6
7

You may want to take a look at the example websocket-raw-data-new-note.qml (opens new window).

# openAiBackendsHook

This hook is called, when the OpenAI service config is reloaded. For example, this is also done when the script engine is reloaded.

You can use it to provide config for custom OpenAI backends, like your own OpenAI API compatible LLMs.

# Method call and parameters

/**
 * This function is called when the OpenAI service config is reloaded
 * It returns a list of objects with config parameters for new OpenAI backends
 */
function openAiBackendsHook() {
    return [
        {
            "id": "my-custom-ai",
            "name": "My Custom AI",
            "baseUrl": "http://localhost:5000",
            "apiKey": "kDFJkjk3asdm",
            "models": ["gpt-3.5-turbo", "gpt-4.0-turbo"],
        },
        {
            "id": "my-custom-ai2",
            "name": "My Custom AI 2",
            "baseUrl": "http://localhost:5001",
            "apiKey": "lOikf7eNdb9",
            "models": ["gpt-3.5-turbo2", "gpt-4.0-turbo2"],
        },
    ];
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

TIP

You can use Registering script settings variables to store the OpenAI backend settings in the script settings.

You may want to take a look at the example custom-openai-backends.qml (opens new window).

← Methods and objects QOwnNotes provides Exposed classes →

Crafted by Patrizio Bekerle with ❤️