Développement pour Sidekick

L’objectif de ce document est d’expliquer comment les développeurs peuvent interagir avec le sidekick et comment le personnaliser au niveau du projet.

Événements

Le sidekick émet les événements suivants :

La payload d’un événement se trouve dans la propriété event.detail .

Écoute des événements

Dans le code de votre projet (par exemple, dans /scripts/scripts.js), vous pouvez réagir aux événements du sidekick comme suit (remplacez foo par le nom de l’événement que vous souhaitez écouter) :

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 });
}

Personnalisation du Sidekick

Vous pouvez personnaliser le sidekick pour votre projet. Vous pouvez ajouter un fichier de configuration /tools/sidekick/config.json au référentiel GitHub de votre projet ou utiliser le service de configuration.

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

Pour toutes les options de configuration disponibles, consultez le schéma de configuration. Voici quelques principes de base pour commencer :

Modules externes

Les modules externes vous permettent d’ajouter des fonctionnalités personnalisées au sidekick, améliorant ainsi l’expérience de vos utilisateurs.

Propriétés communes du plug-in

Les propriétés suivantes s’appliquent à tous les types de plug-in :

Plug-ins basés sur une URL

Vous pouvez spécifier un url qui s’ouvrira dans un nouvel onglet lorsque vous cliquerez sur le bouton du plug-in :

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

Plug-ins basés sur un événement

Vous pouvez également spécifier le nom d’un event à déclencher lorsque vous cliquez sur le bouton du plug-in. Cela permet l’exécution de code JavaScript personnalisé dans le contexte de votre page en écoutant l’événement sur l’élément de sidekick. Les événements personnalisés comportent un préfixe custom:. Pour votre commodité, l’événement personnalisé distribué contient une copie de l’état actuel du sidekick.

Remarque : les modules externes basés sur des événements ne peuvent être utilisés que dans les environnements suivants : Développement, Aperçu, En direct et Production. L’exécution de code personnalisé n’est pas possible dans Modifier ou Admin.

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

Dans le code de votre projet (par exemple, dans /scripts/scripts.js), vous pouvez réagir à l’événement comme suit :

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 });
}

Types de plug-ins spéciaux

Plug-ins de palette

Les palettes sont des variantes de modules externes basés sur des URL qui chargent l’URL configurée en ligne au lieu d’ouvrir un nouvel onglet.

L'exemple suivant crée une palette standard placée en bas à gauche de la fenêtre :

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

Si vous souhaitez modifier la taille et le positionnement de votre palette, utilisez paletteRect :

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

Plug-ins de conteneur

Les conteneurs vous permettent de regrouper des modules externes et d’économiser de l’espace dans la barre d’outils. Cliquez sur un plug-in de conteneur pour simplement activer/désactiver sa liste déroulante. Il ne peut pas avoir sa propre URL ou action d’événement.

L’exemple suivant crée un conteneur nommé « Tools » et y place un module externe « Foo » :

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

Plug-ins de badge

Les badges vous permettent d’ajouter des libellés au sidekick sous certaines conditions. Ils sont rendus sur le côté droit de la barre d’outils. Les badges ont un simple objectif décoratif et ne peuvent pas être utilisés.

L’exemple suivant ajoute un badge « Phase » au sidekick dans l’environnement de prévisualisation :

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

URL de modification personnalisées

Si votre projet n’utilise pas SharePoint ou Google Drive comme source de contenu, vous pouvez indiquer au sidekick comment créer un lien vers votre environnement de modification personnalisé lorsque l’utilisateur clique sur Modifier.

Les deux options de configuration suivantes sont disponibles :

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

Vues spéciales

Vous pouvez spécifier une vue spéciale vers laquelle le sidekick redirige lorsque l’URL de l’onglet actif correspond à un certain modèle. Cela peut vous aider à offrir une expérience utilisateur transparente sur différents types de médias et permet également l’exécution de code personnalisé (modules externes basés sur un événement). L’URL de la ressource d’origine sera disponible dans un paramètre de requête url.

Les propriétés path et viewer sont obligatoires. Si vous le souhaitez, vous pouvez spécifier une title qui s’affichera en haut et fournir des titres localisés dans un objet titleI18n :

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

Au chemin d’accès spécifié par viewer, ajoutez un fichier HTML à votre référentiel GitHub, par exemple :

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

Ajoutez un fichier CSS facultatif dans le même répertoire et un fichier JS avec votre logique personnalisée, par exemple :

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);
}

Workflow de développement

Les workflows suivants sont conçus pour le développement de sidekick détaché afin d’éviter toute perturbation involontaire des auteurs sur votre site de production :

Utilisation d’une copie de site

Si la configuration de votre site est stockée dans le Service de configuration, vous pouvez utiliser des copies de site temporaires pour le développement du sidekick :

Remarque : lors de l’utilisation du sidekick dans un environnement d’éditeur (Google Drive ou Microsoft Sharepoint), il charge la configuration à partir du site d’origine par défaut. Si vous souhaitez que le sidekick vous permette de choisir la configuration à charger, commencez par ajouter le nouveau site à votre sidekick à partir de l’aperçu ou de l’URL active. Le sidekick affiche désormais un sélecteur avec tous les sites correspondants.

Utilisation d’une branche de référentiel

Si la configuration de votre site n’est pas stockée dans le Service de configuration, vous pouvez utiliser une branche dans GitHub pour le développement du sidekick :

Attention : ne validez jamais directement la branche main de votre référentiel d’origine. Créez toujours une branche et demandez une révision de vos modifications par le biais d’une demande d’extraction avant de fusionner dans main.

Remarque : lors de l’utilisation du sidekick dans un environnement d’éditeur (Google Drive ou Microsoft Sharepoint), il charge la configuration à partir du site d’origine par défaut. Si vous souhaitez que le sidekick vous permette de choisir la configuration à charger, commencez par ajouter le nouveau site à votre sidekick à partir de l’aperçu ou de l’URL active. Le sidekick affiche désormais un sélecteur avec tous les sites correspondants.