Beispiel Plugin: Erweitertes Plugin

In diesem Kapitel wird das Beispiel Plugin: Hello World um folgende Funktionalität erweitert

  1. eine Schaltfläche in der Kontrollleiste
  2. Kommunikation zwischen der Schaltfläche und der Pane
  3. aktuelle Kontaktdetails in der Pane
  4. Einstellungen für das Plugin
  5. einem Dialog in der Anwendung

Der vollständige Sourcecode kann hier heruntergeladen werden.

Voraussetzung

Sie benötigen den Sourcecode aus dem vorherigen Kapitel. Falls Sie das Kapitel übersprungen haben, können Sie den Sourcecode hier herunterladen.

Schaltfläche erstellen

Um eine neue Schaltfläche zu erstellen, erstellen Sie die Datei button.js mit folgendem Inhalt:

window.onButtonClick = function() {

}

Diese Datei müssen Sie wieder in der manifest.json bekannt machen:

{
    "buttons": [
         {
             "buttonId": "sample-button",
             "extensionPoint": ["agentclient.*"],
             "label": "Hello world example",
             "icon": "extension",
             "filename": "button.js",
             "function": "onButtonClick"
         }
    ]
}

Die Funktion onButtonClick wird immer dann aufgerufen, wenn der Benutzer die Schaltfläche betätigt. Aktuell besitzt die Funktion noch keine Logik. Sie wird im nächsten Kapitel hinzugefügt.

Die Beschreibung der einzelnen Manifest Attribute finden Sie hier: Erweiterungstyp Schaltfläche.

Kommunikation innerhalb und zwischen Plugins

In diesem Kapitel erfahren Sie, wie Sie innerhalb der Anwendung kommunizieren können. Sie können diesen Mechanismus benutzen um zwischen zwei Extension Points eines Plugins zu kommunizieren, aber auch um zwischen zwei unterschiedlichen Plugins zu kommunizieren.

Wie im Kapitel Clientseitige Events beschrieben, existiert das globale Objekt lcapi.messageBus. Diesen Message Bus können Sie im Beispiel Plugin dazu nutzen um zwischen der Schaltfläche und der Pane zu kommunizieren.

Ändern Sie hierfür die button.js Datei wie folgt:

1
2
3
4
5
6
7
8
9
window.onButtonClick = function() {
   var eventName = 'sample-hello-world-button-clicked';
   var eventDetails = {
      message: 'Time of click: ' + new Date().toUTCString(),
      extensionPoint: window.extensionPoint
   };

   lcapi.messageBus.emit(eventName, eventDetails);
}

Den Eventnamen sollten Sie möglichst eindeutig wählen um Konflikte mit anderen Plugins auszuschließen (siehe Zeile 2).

In den eigentlichen Daten (Zeile 3) sollten Sie immer den Extension Point mitschicken (Zeile 5). Somit können Sie auf der Empfängerseite entscheiden, ob das Event für Sie relevant ist. Hierfür können Sie in Ihrem Code immer auf die globale Variable window.extensionPoint zugreifen, die den entsprechenden Extension Point enthält.

Note

Wenn Sie Ihr Plugin für mehr als einen Extension Point konfiguriert haben, bspw. für agentclient.livechat.private.*, existieren zur Laufzeit mehrere Instanzen Ihres Codes. In dem Beispiel eine für agentclient.livechat.private.textchat und eine für agentclient.livechat.private.videochat.

Um nun auf der Empfängerseite den Zeitpunkt des Klicks anzuzeigen, ändern Sie die Datei pane.html und fügen Sie folgenden Javascript Code,

1
2
3
4
5
6
7
lcapi.messageBus.on('sample-hello-world-button-clicked', function(event) {

   if (event.extensionPoint === window.extensionPoint) {
      document.querySelector('#clickInfo').textContent = event.message;
   }

});

und außerdem folgenden HTML Code hinzu:

<p id="clickInfo"></p>

Wie beschrieben, wird zuerst überprüft ob das Event für den Extension Point bestimmt ist (Zeile 3), und anschließend die UI des Plugins aktualisiert (Zeile 4).

Clientseitige UI Events

Für viele Anwendungsfälle muss das Plugin wissen welche Daten aktuell in der GUI angezeigt werden, bspw. welcher TextChat aktuell mit welcher Person geöffnet ist.

Hierfür gibt es die sogenannten clientseitigen Events. Möchten Sie zum Beispiel die aktuellen Kontaktdetails in einem TextChat anzeigen, können Sie auf das Event ui-textchat-model-changed hören.

Ergänzen Sie hierfür folgenden Code in der Datei pane.html.

HTML Änderungen:

<p id="contactName"></p>

JavaScript Änderungen:

1
2
3
4
5
6
7
8
lcapi.messageBus.on('ui-textchat-model-changed', function(event) {

   if (event.extensionPoint === window.extensionPoint) {
      var contactName = (event.model && event.model.contact)? event.model.contact.u8sDisplayName : 'No contact selected';
      document.querySelector('#contactName').textContent = contactName;
   }

});

In Zeile 3 wird geprüft, ob das Event für den richtigen Extension Point bestimmt ist. Falls er das ist, wird der Kontaktname in der UI des Plugins aktualisiert (siehe Zeile 4 und 5).

Einstellungen für Ihr Plugin

Um einen Einstellungsdialog für das Plugin zu erstellen, legen Sie eine neue Datei mit dem Namen settings.html an und hinterlegen diese Datei im Manifest:

{
    "settings": {
        "filename": "settings.html",
        "function": "onClose"
    }
}

In der settings.html können Sie die Einstellungen über die lcapi.storage API speichern. Im Beispiel werden die Einstellungen beim Öffnen des Dialogs vom Server geladen (Zeile 18-20) und gespeichert sobald der Benutzer den Einstellungsdialog schließt (Zeile 23-25).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
</head>
<body>

  <label for="sample">Sample</label>
  <input id="sample" type="text">

  <script>

    let pluginId = 'sample-hello-world';
    let settingsKey = 'sample';
    let inputElement = document.querySelector('#sample');

    // Read settings initially (every time the dialog is opened)
    lcapi.storage.user.get(pluginId, settingsKey, function(err, res) {
      inputElement.value = res;
    });

    // Save when settings dialog is closed
    window.onClose = function() {
      lcapi.storage.user.set(pluginId, settingsKey, inputElement.value);
    };

  </script>

</body>
</html>

Dialog in der Anwendung

Um einen neuen Dialog zu definieren, erweitern Sie die manifest.json Datei wie folgt (die einzelnen Attribute sind im Kapitel Erweiterungstyp Dialog beschrieben):

{
   "dialogs": [
      {
         "dialogId": "sample-dialog",
         "width": "300px",
         "height": "100px",
         "filename": "dialog.html",
         "functionSave": "onSave"
      }
   ]
}

Als Beispiel können Sie folgende dialog.html anlegen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
  </head>
  <body>

    <h1>Sample Dialog</h1>

    <label for="sampleInput">A sample field</label>
    <input type="text" id="sampleInput" required>

    <script>

      window.onSave = function(cb) {
        let isValid = document.querySelector('#sampleInput').checkValidity();

        cb(isValid);
      };

    </script>

  </body>
</html>

Der Dialog besteht aus einem Textfeld (Zeile 11), das als Pflichtfeld deklariert ist. Beim Speichern des Dialogs wird überprüft, ob das Feld gefüllt ist. Abhängig vom Ergebnis wird der Dialog geschlossen (siehe Zeile 18). Bei true wird er geschlossen, bei false bleibt er geöffnet und Sie können bspw. eine Fehlermeldung ausgeben.

Um den Dialog anzuzeigen, können Sie in der pane.html eine neue Schaltfläche definieren, die über die lcapi.ui.dialog API den Dialog öffnet:

<button onclick="onOpenDialog()">Show dialog</button>

<script>
  window.onOpenDialog = function() {
     lcapi.ui.dialog.open('sample-hello-world', 'sample-dialog');
  };
</script>