Sviluppo per Sidekick

L’obiettivo di questo documento è quello di spiegare come gli sviluppatori possono interagire con la barra laterale e come può essere personalizzata a livello di progetto.

Eventi

La barra laterale genera i seguenti eventi:

Il payload di un evento si trova nella proprietà event.detail.

Ascolto di eventi

Nel codice del progetto (ad esempio, in /scripts/scripts.js), è possibile reagire agli eventi della barra laterale come segue (sostituire foo con il nome dell'evento che si desidera ascoltare):

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

Personalizzazione di Sidekick

Puoi personalizzare la barra laterale per il progetto. È possibile aggiungere un file di configurazione /tools/sidekick/config.json all'archivio GitHub del progetto o utilizzare il servizio di configurazione.

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

Per tutte le opzioni di configurazione disponibili, vedere schema di configurazione. Ecco alcune nozioni di base per iniziare:

Plug-in

I plug-in consentono di aggiungere funzionalità personalizzate alla barra laterale, migliorando l’esperienza degli utenti.

Proprietà plug-in comuni

Le seguenti proprietà sono applicabili a tutti i tipi di plug-in:

Plug-in basati su URL

È possibile specificare un url che verrà aperto in una nuova scheda quando si fa clic sul pulsante del plug-in:

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

Plug-in basati su eventi

In alternativa, è possibile specificare il nome di un event da attivare quando si fa clic sul pulsante del plug-in. Questo consente l’esecuzione di codice JavaScript personalizzato nel contesto della pagina mediante l’ascolto dell’evento sull’elemento della barra laterale. Gli eventi personalizzati avranno un prefisso custom:. Per comodità, l’evento personalizzato inviato contiene una copia dello stato corrente della barra laterale.

Nota: i plug-in basati su eventi possono essere utilizzati solo nei seguenti ambienti: sviluppo, anteprima, live e produzione. Non è possibile eseguire codice personalizzato in Modifica o in Amministratore.

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

Nel codice del progetto (ad esempio, in /scripts/scripts.js), è possibile reagire all'evento nel modo seguente:

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

Tipi di plug-in speciali

Plug-in tavolozza

Le palette sono varianti di plug-in basati su URL che caricano l’URL configurato in linea invece di aprire una nuova scheda.

Nell'esempio seguente viene creata una tavolozza standard posizionata nella parte inferiore sinistra della finestra:

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

Se si desidera modificare le dimensioni e il posizionamento della tavolozza, utilizzare paletteRect:

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

Plug-in contenitore

I contenitori consentono di raggruppare i plug-in e di risparmiare spazio nella barra degli strumenti. Facendo clic su un plug-in contenitore, si attiva semplicemente il menu a discesa, non è possibile impostare un URL o un’azione evento personalizzati.

L’esempio che segue crea un contenitore denominato "Tools" (Strumenti) e contiene un plug-in "Foo":

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

Plug-in badge

I badge consentono di aggiungere etichette alla barra laterale in determinate condizioni. Il rendering viene eseguito sul lato destro della barra degli strumenti. I badge hanno uno scopo puramente decorativo e non possono essere cliccati.

L’esempio seguente aggiunge un badge "Stage" alla barra laterale nell’ambiente di anteprima:

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

URL di modifica personalizzati

Se il progetto non utilizza SharePoint o Google Drive come origine di contenuto, puoi indicare alla barra laterale come collegarti all'ambiente di modifica personalizzato quando l'utente fa clic su Modifica.

Sono disponibili le seguenti due opzioni di configurazione:

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

Visualizzazioni speciali

Puoi specificare una visualizzazione speciale alla quale reindirizzare la barra laterale quando l’URL della scheda corrente corrisponde a un determinato pattern. Questo può aiutarti a fornire un’esperienza utente fluida tra diversi tipi di contenuti multimediali e consente anche l’esecuzione di codice personalizzato (plug-in basati su eventi). L'URL della risorsa originale sarà disponibile in un parametro di query url.

Le proprietà path e viewer sono obbligatorie Facoltativamente, è possibile specificare un title che verrà visualizzato nella parte superiore ed è possibile fornire titoli localizzati in un oggetto titleI18n:

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

Nel percorso specificato da viewer, aggiungi un file HTML all'archivio GitHub, ad esempio:

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

Aggiungi un file CSS facoltativo nella stessa directory e un file JS con la logica personalizzata, ad esempio:

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

Flusso di lavoro di sviluppo

I seguenti flussi di lavoro sono progettati per lo sviluppo della barra laterale separata per evitare interruzioni non intenzionali per gli autori sul sito di produzione:

Utilizzo di una copia del sito

Se la configurazione del sito è archiviata nel Servizio di configurazione, è possibile utilizzare copie del sito temporanee per lo sviluppo della barra laterale:

Nota: quando si utilizza la barra laterale in un ambiente di editor (Google Drive o Microsoft Sharepoint), per impostazione predefinita la configurazione viene caricata dal sito originale. Se si desidera che la barra laterale consenta di scegliere la configurazione da caricare, aggiungere il nuovo sito alla barra laterale dall'anteprima o dall'URL attivo. Ora nella barra laterale viene visualizzato un selettore con tutti i siti corrispondenti.

Utilizzo di un ramo dell’archivio

Se la configurazione del sito non è archiviata nel Servizio di configurazione, è possibile utilizzare un ramo in GitHub per lo sviluppo della barra laterale:

Attenzione: non eseguire mai il commit diretto nel ramo main nell'archivio originale. Crea sempre un ramo e chiedi una revisione delle modifiche tramite richiesta pull prima di unirle in main.

Nota: quando si utilizza la barra laterale in un ambiente di editor (Google Drive o Microsoft Sharepoint), per impostazione predefinita la configurazione viene caricata dal sito originale. Se si desidera che la barra laterale consenta di scegliere la configurazione da caricare, aggiungere il nuovo sito alla barra laterale dall'anteprima o dall'URL attivo. Ora nella barra laterale viene visualizzato un selettore con tutti i siti corrispondenti.