Add scripting hook insertAttachmentHook (#1645)

CHANGELOG.md

@@ -4,6 +4,11 @@
 - a preview code block highlighting issue was fixed (for [#1933](https://github.com/pbek/QOwnNotes/issues/1933))
 - the *distraction free mode* is now disabled when no note is selected
   (for [#1936](https://github.com/pbek/QOwnNotes/pull/1936), thank you @fnkabit)
+- a new scripting hook `insertAttachmentHook` was added that is executed when an
+  attachment file is inserted into the current note (for [#1645](https://github.com/pbek/QOwnNotes/issues/1645))
+    - please take a look at the
+      [handleNoteNameHook documentation](https://www.qownnotes.org/scripting/hooks.html#insertattachmenthook)
+      for more information
 
 ## 20.11.1
 - a possibly not updating note count when notes were removed was fixed

docs/scripting/examples/example.qml

@@ -88,18 +88,31 @@ QtObject {
     }
     
     /**
-     * This function is called when media file is inserted into the note
+     * 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
      * 
      * @param fileName string the file path of the source media file before it was copied to the media folder
-     * @param mediaMarkdownText string the markdown text of the media file, e.g. ![my-image](file://media/505671508.jpg)
+     * @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, mediaMarkdownText) {
+    function insertMediaHook(fileName, markdownText) {
         script.log("mediafile was inserted: " + fileName);
         return "";
     }
-    
+
+    /**
+     * 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
+     *
+     * @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) {
+        script.log("attachment was inserted: " + fileName);
+        return "";
+    }
+
     /**
      * This function is called when html or a media file is pasted to a note with `Ctrl + Shift + V`
      * 

src/mainwindow.cpp

@@ -7054,6 +7054,9 @@ bool MainWindow::insertAttachment(QFile *file, const QString &title) {
     QString text = currentNote.getInsertAttachmentMarkdown(file, title);
 
     if (!text.isEmpty()) {
+        ScriptingService *scriptingService = ScriptingService::instance();
+        // attempts to ask a script for another markdown text
+        text = scriptingService->callInsertAttachmentHook(file, text);
         qDebug() << __func__ << " - 'text': " << text;
 
         QOwnNotesMarkdownTextEdit *textEdit = activeNoteTextEdit();

src/services/scriptingservice.cpp

@@ -346,23 +346,6 @@ void ScriptingService::outputMethodsOfObject(QObject *object) {
     }
 }
 
-/**
- * Calls the insertMediaHook function for an object
- */
-QString ScriptingService::callInsertMediaHookForObject(
-    QObject *object, QFile *file, const QString &markdownText) {
-    if (methodExistsForObject(
-            object, QStringLiteral("insertMediaHook(QVariant,QVariant)"))) {
-        QVariant newMarkdownText;
-        QMetaObject::invokeMethod(
-            object, "insertMediaHook", Q_RETURN_ARG(QVariant, newMarkdownText),
-            Q_ARG(QVariant, file->fileName()), Q_ARG(QVariant, markdownText));
-        return newMarkdownText.toString();
-    }
-
-    return QString();
-}
-
 /**
  * Calls the insertMediaHook function for all script components
  * This function is called when media file is inserted into the note
@@ -375,10 +358,46 @@ QString ScriptingService::callInsertMediaHook(QFile *file,
         i.next();
         ScriptComponent scriptComponent = i.value();
 
-        QString text = callInsertMediaHookForObject(scriptComponent.object,
-                                                    file, markdownText);
-        if (!text.isEmpty()) {
-            return text;
+        if (methodExistsForObject(
+            scriptComponent.object, QStringLiteral("insertMediaHook(QVariant,QVariant)"))) {
+            QVariant newMarkdownText;
+            QMetaObject::invokeMethod(
+                scriptComponent.object, "insertMediaHook", Q_RETURN_ARG(QVariant, newMarkdownText),
+                Q_ARG(QVariant, file->fileName()), Q_ARG(QVariant, markdownText));
+            QString result = newMarkdownText.toString();
+
+            if (!result.isEmpty()) {
+                return result;
+            }
+        }
+    }
+
+    return markdownText;
+}
+
+/**
+ * Calls the insertMediaHook function for all script components
+ * This function is called when media file is inserted into the note
+ */
+QString ScriptingService::callInsertAttachmentHook(QFile *file,
+                                                   QString markdownText) {
+    QMapIterator<int, ScriptComponent> i(_scriptComponents);
+
+    while (i.hasNext()) {
+        i.next();
+        ScriptComponent scriptComponent = i.value();
+
+        if (methodExistsForObject(
+            scriptComponent.object, QStringLiteral("insertAttachmentHook(QVariant,QVariant)"))) {
+            QVariant newMarkdownText;
+            QMetaObject::invokeMethod(
+                scriptComponent.object, "insertAttachmentHook", Q_RETURN_ARG(QVariant, newMarkdownText),
+                Q_ARG(QVariant, file->fileName()), Q_ARG(QVariant, markdownText));
+            QString result = newMarkdownText.toString();
+
+            if (!result.isEmpty()) {
+                return result;
+            }
         }
     }
 

src/services/scriptingservice.h

@@ -38,6 +38,7 @@ class ScriptingService : public QObject {
     QQmlEngine *engine() const;
     void initComponents();
     QString callInsertMediaHook(QFile *file, QString markdownText);
+    QString callInsertAttachmentHook(QFile *file, QString markdownText);
     QVariant callNoteTaggingHook(const Note &note, const QString &action,
                                  const QString &tagName = QString(),
                                  const QString &newTagName = QString());
@@ -207,8 +208,6 @@ class ScriptingService : public QObject {
     QMap<int, ScriptComponent> _scriptComponents;
     QHash<int, QList<QVariant>> _settingsVariables;
     bool methodExistsForObject(QObject *object, const QString &method) const;
-    QString callInsertMediaHookForObject(QObject *object, QFile *file,
-                                         const QString &markdownText);
     QString callNoteToMarkdownHtmlHookForObject(ScriptComponent *scriptComponent, Note *note,
                                                 const QString &html, const bool forExport);
     void initComponent(const Script &script);

webpage/src/scripting/hooks.md

@@ -53,17 +53,38 @@ You may want to take a look at the example
 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
 ```js
 /**
- * This function is called when media file is inserted into the note
- * If this function is defined in multiple scripts, then the first script that returns a non-empty string wins
- *
  * @param fileName string the file path of the source media file before it was copied to the media folder
- * @param mediaMarkdownText string the markdown text of the media file, e.g. ![my-image](file://media/505671508.jpg)
+ * @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, mediaMarkdownText);
+function insertMediaHook(fileName, markdownText);
+```
+
+You may want to take a look at the example
+[example.qml](https://github.com/pbek/QOwnNotes/blob/develop/docs/scripting/examples/example.qml).
+
+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
+```js
+/**
+ * @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);
 ```
 
 You may want to take a look at the example