Entwickeln für Sidekick

In diesem Dokument soll erläutert werden, wie Entwickler mit dem Sidekick interagieren können und wie er auf Projektebene angepasst werden kann.

Ereignisse

Der Sidekick gibt die folgenden Ereignisse aus:

Die Payload eines Ereignisses befindet sich in der event.detail.

Überwachen von Ereignissen

In Ihrem Projekt-Code (z. B. in /scripts/scripts.js) können Sie wie folgt auf Sidekick-Ereignisse reagieren (ersetzen Sie foo durch den Namen des Ereignisses, das Sie überwachen möchten):

const doFoo = ({ detail: payload }) => {
  console.log('something happened', payload);
  // your custom code goes here
};

const sk = document.querySelector('aem-sidekick');
if (sk) {
  // sidekick already loaded
  sk.addEventListener('foo', doFoo);
} else {
  // wait for sidekick to be loaded
  document.addEventListener('sidekick-ready', () => {
    // sidekick now loaded
    document.querySelector('aem-sidekick')
      .addEventListener('foo', doFoo);
  }, { once: true });
}

Anpassen von Sidekick

Sie können den Sidekick für Ihr Projekt anpassen. Sie können eine /tools/sidekick/config.json Konfigurationsdatei zum GitHub-Repository Ihres Projekts hinzufügen oder den Konfigurationsdienst verwenden.

{
  "project": "My project",
  "host": "www.mydomain.prod",
  "plugins": []
}

Alle verfügbaren Konfigurationsoptionen finden Sie im config-Schema. Im Folgenden finden Sie einige Grundlagen für den Einstieg:

Plug-ins

Plug-ins ermöglichen es Ihnen, dem Sidekick benutzerdefinierte Funktionen hinzuzufügen, wodurch das Benutzererlebnis verbessert wird.

Allgemeine Plug-in-Eigenschaften

Die folgenden Eigenschaften gelten für alle Plug-in-Typen:

URL-basierte Plug-ins

Sie können einen url angeben, der in einer neuen Registerkarte geöffnet wird, wenn auf die Plug-in-Schaltfläche geklickt wird:

{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo.html"
    }
  ]
}

Ereignisbasierte Plug-ins

Sie können auch den Namen eines event angeben, der beim Klicken auf die Plug-in-Schaltfläche ausgelöst werden soll. Dies ermöglicht die Ausführung von benutzerdefiniertem JavaScript-Code im Kontext Ihrer Seite, indem auf das -Ereignis im Sidekick-Element gewartet wird. Benutzerdefinierte Ereignisse haben ein custom: Präfix. Zur Vereinfachung enthält das benutzerdefinierte Ereignis , das gesendet wird, eine Kopie des aktuellen Sidekick-Status.

Hinweis Ereignisbasierte Plug-ins können nur in den folgenden Umgebungen verwendet werden: Entwicklung, Vorschau, Live und Produktion. Das Ausführen von benutzerdefiniertem Code ist in Bearbeiten oder Admin nicht möglich.

{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "event": "foo"
    }
  ]
}

In Ihrem Projekt-Code (z. B. in /scripts/scripts.js) können Sie wie folgt auf das Ereignis reagieren:

const doFoo = ({ detail: payload }) => {
  console.log('a custom event happened', payload);
  // your custom code goes here
};

const sk = document.querySelector('aem-sidekick');
if (sk) {
  // sidekick already loaded
    sk.addEventListener('custom:foo', doFoo);
} else {
  // wait for sidekick to be loaded
  document.addEventListener('sidekick-ready', () => {
    // sidekick now loaded
    document.querySelector('aem-sidekick')
      .addEventListener('custom:foo', doFoo);
  }, { once: true });
}

Spezielle Plug-in-Typen

Palette-Plug-ins

Paletten sind Varianten von URL-basierten Plug-ins, die die konfigurierte URL inline laden, anstatt eine neue Registerkarte zu öffnen.

Im folgenden Beispiel wird eine Standardpalette unten links im Fenster erstellt:

{
  "plugins": [
    {
      "id": "tools",
      "title": "Tools",
      "url": "/tools/sidekick/foo-palette.html",
      "isPalette": true
    }
  ]
}

Wenn Sie die Größe und Positionierung Ihrer Palette ändern möchten, verwenden Sie paletteRect:

{
  "plugins": [
    {
      "id": "tools",
      "title": "Tools",
      "url": "/tools/sidekick/foo-palette.html",
      "isPalette": true,
      "paletteRect": "top:150px;left:7%;height:675px;width:85vw;"
    }
  ]
}

Container-Plug-ins

Container ermöglichen es Ihnen, Plug-ins zu gruppieren und Platz in der Symbolleiste zu sparen. Durch Klicken auf ein Container-Plug-in wird einfach dessen Dropdown-Liste umgeschaltet. Es kann keine eigene URL oder Ereignisaktion haben.

Im folgenden Beispiel wird ein Container mit dem Namen „Tools“ erstellt und ein Plug-in mit dem Namen „Foo“ darin platziert:

{
  "plugins": [
    {
      "id": "tools",
      "title": "Tools",
      "isContainer": true
    },
    {
      "id": "foo",
      "containerId": "tools",
      "title": "Foo",
      "event": "foo"
    }
  ]
}

Badge-Plug-ins

Mit Abzeichen können Sie unter bestimmten Bedingungen Kennzeichnungen zum Sidekick hinzufügen. Sie werden auf der rechten Seite der Symbolleiste gerendert. Abzeichen haben lediglich einen dekorativen Zweck und können nicht angeklickt werden.

Im folgenden Beispiel wird dem Sidekick in der Vorschau-Umgebung das Badge „Staging“ hinzugefügt:

{
  "plugins": [
    {
      "id": "stage",
      "title": "Stage",
      "isBadge": true,
      "environments" ["preview"]
    }
  ]
}

Benutzerdefinierte URLs bearbeiten

Wenn Ihr Projekt SharePoint oder Google Drive nicht als Inhaltsquelle verwendet, können Sie dem Sidekick mitteilen, wie eine Verknüpfung mit Ihrer benutzerdefinierten Bearbeitungsumgebung hergestellt werden soll, wenn der Benutzer auf Bearbeiten klickt.

Die folgenden beiden Konfigurationsoptionen sind verfügbar:

{
  "editUrlLabel": "Your Editor",
  "editUrlPattern": "{{contentSourceUrl}}{{pathname}}?cmd=open"
}

Besondere Ansichten

Sie können eine spezielle Ansicht für den Sidekick angeben, zu der umgeleitet werden soll, wenn die URL der aktuellen Registerkarte einem bestimmten Muster entspricht. Dies kann Ihnen dabei helfen, ein nahtloses Benutzererlebnis über verschiedene Medientypen hinweg bereitzustellen, und ermöglicht auch die Ausführung von benutzerdefiniertem Code (ereignisbasierte Plug-ins). Die ursprüngliche Ressourcen-URL ist in einem url Abfrageparameter verfügbar.

Die Eigenschaften path und viewer sind obligatorisch. Optional können Sie einen title angeben, der oben angezeigt wird, und Sie können lokalisierte Titel in einem titleI18n-Objekt bereitstellen:

{
  "specialViews": [
    {
      "title": "Custom JSON Viewer",
      "path" : "**.json",
      "viewer": "/tools/sidekick/custom-json-viewer/index.html"
    }
  ]
}

Fügen Sie an dem von viewer angegebenen Pfad eine HTML-Datei zu Ihrem GitHub-Repository hinzu, z. B.:

<html>
<head>
  <title>Custom JSON Viewer</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="./custom-json-viewer.css">
  <!-- add your custom code -->
  <script src="./custom-json-viewer.js"></script>
</head>
  <body>
  </body>
</html>

Fügen Sie eine optionale CSS-Datei im selben Verzeichnis und eine JS-Datei mit Ihrer benutzerdefinierten Logik hinzu, z. B.:

try {
  // get the resource URL from the url query parameter
  const url = new URL(window.location.href).searchParams.get('url');
  if (url) {
    const res = await fetch(url);
    if (res.ok) {
      const text = await res.text();
      const data = JSON.parse(text);
      // do something with the data, e.g.
      document.body.innerHTML = `
        <pre>
          ${JSON.stringify(data, null, 2)}
        </pre>
       `;
    } else {
      throw new Error(`failed to load ${url}: ${res.status}`);
    }
  }
} catch (e) {
  console.error('error rendering custom json view', e);
}

Entwicklungs-Workflow

Die folgenden Workflows sind für die Entwicklung separater Sidekicks konzipiert, um unbeabsichtigte Unterbrechungen für die Autoren auf Ihrer Produktions-Site zu verhindern:

Verwenden einer Site Copy

Wenn die Konfiguration Ihrer Site im Konfigurations-Service gespeichert ist, können Sie temporäre Site-Kopien für die Sidekick-Entwicklung verwenden:

Hinweis: Bei Verwendung des Sidekicks in einer Editor-Umgebung (Google Drive oder Microsoft Sharepoint) wird die Konfiguration standardmäßig von der ursprünglichen Site geladen. Wenn Sie möchten, dass Sie im Sidekick auswählen können, welche Konfiguration geladen werden soll, Sie Ihrem Sidekick zuerst über die Vorschau- oder LiveURL die neue Site hinzufügen. Im Sidekick wird nun eine Auswahl mit allen übereinstimmenden Sites angezeigt.

Verwenden einer Repository-Verzweigung

Wenn die Konfiguration Ihrer Site nicht im Konfigurations-Service gespeichert ist, können Sie eine Verzweigung in GitHub für die Sidekick-Entwicklung verwenden:

Achtung: Sie niemals einen direkten Commit für die main Verzweigung in Ihrem ursprünglichen Repository an. Erstellen Sie immer eine Verzweigung und bitten Sie per Pull-Anfrage um eine Überprüfung Ihrer Änderungen, bevor Sie sie mit main zusammenführen.

Hinweis: Bei Verwendung des Sidekicks in einer Editor-Umgebung (Google Drive oder Microsoft Sharepoint) wird die Konfiguration standardmäßig von der ursprünglichen Site geladen. Wenn Sie möchten, dass Sie im Sidekick auswählen können, welche Konfiguration geladen werden soll, Sie Ihrem Sidekick zuerst über die Vorschau- oder LiveURL die neue Site hinzufügen. Im Sidekick wird nun eine Auswahl mit allen übereinstimmenden Sites angezeigt.