Che cos’è la libreria sidekick?
La libreria sidekick è un’estensione per la barra laterale di AEM che consente agli sviluppatori di creare strumenti guidati dall’interfaccia utente per gli autori di contenuto. Include un plug-in per blocchi integrato che può mostrare agli autori un elenco di tutti i blocchi in modo intuitivo, eliminando la necessità di ricordare o cercare ogni variante di un blocco. Gli sviluppatori possono anche scrivere i propri plug-in per la libreria sidekick.
Come si utilizza la libreria Sidekick?
I passaggi seguenti descrivono in dettaglio come impostare la libreria di barre laterali e configurare il plug-in blocchi.
Impostazione foglio libreria
La libreria della barra laterale viene compilata con i plug-in e il contenuto del plug-in utilizzando un foglio.
1. Iniziare creando una directory in sharepoint o gdrive in cui si desidera archiviare il contenuto della libreria. È consigliabile archiviare il contenuto in /tools/sidekick (o qualsiasi altro nome) nella radice del punto di montaggio. Nei passaggi successivi si presuppone che la directory sia denominata /tools/sidekick.
2. Creare quindi una cartella di lavoro (un file di Excel) nella directory /tools/sidekick denominata library (o qualsiasi altro nome). Ogni foglio della cartella di lavoro rappresenta un plug-in che verrà caricato dalla libreria di Sidekick. Il nome del foglio determina il nome del plug-in da caricare. Tutti i dati contenuti nel foglio verranno passati al plug-in al momento del caricamento. Il nome del foglio del plug-in deve essere preceduto da helix-. Ad esempio, per caricare un plug-in denominato tags, creare un foglio denominato helix-tags.
3. Per questo tutorial verrà creato un foglio per il plug-in blocks. Crea un foglio (o rinomina il foglio predefinito), chiamalo `helix-blocks` e lascialo vuoto per il momento.
Plug-in blocchi
La libreria Sidekick include un plug-in blocks.
Configurazione plug-in blocchi
Per generare il contenuto per il plug-in blocchi, è necessario preparare un documento Word separato per ogni blocco che si desidera includere.
1. Creare una directory all'interno della directory /tools/sidekick in cui memorizzare tutte le varianti di blocco. Ad esempio, è possibile creare una directory denominata blocks in /tools/sidekick.
2. Per questo esempio, supponiamo di voler definire tutte le varianti di un blocco denominato columns. Creare innanzitutto un documento di Word denominato columns nella directory blocks e fornire esempi di tutte le varianti del blocco columns. Dopo ogni variante del blocco, aggiungi un delimitatore di sezione.
3. Anteprima e pubblicazione del documento columns.
4. Aprire la cartella di lavoro della libreria creata nell'ultima sezione, all'interno del foglio helix-blocks, creare due colonne denominate name e path.
6. Successivamente, è necessario aggiungere una riga per il blocco columns. Aggiungi il nome del blocco nella prima colonna e l’URL al documento che definisce le varianti di blocco nella seconda colonna. Se ad esempio si desidera aggiungere il blocco columns, è possibile creare una riga con il nome Columns e il percorso /tools/sidekick/blocks/columns. Affinché la libreria funzioni tra ambienti diversi (page, live, prod), non utilizzare un URL assoluto per la colonna del percorso.
7. Anteprima e pubblicazione della cartella di lavoro library.
> Poiché i blocchi di esempio sono in fase di pubblicazione, è necessario utilizzare metadati in blocco per escludere il contenuto all'interno di /tools/** dall'indicizzazione.
Esempio library.xlsx
Metadati libreria
I plug-in dei blocchi supportano un tipo speciale di blocco denominato library metadata che consente agli sviluppatori di comunicare al plug-in dei blocchi alcune informazioni sul blocco o su come eseguirne il rendering.
Opzioni di metadati della libreria supportate
Metadati libreria predefiniti e metadati libreria
Esistono due tipi di library metadata. I metadati della libreria che si trovano all'interno di una sezione contenente il blocco, o default library metadata che si applica al documento nel suo insieme e si trova in una sezione a sé stante (un blocco denominato library metadata come unico elemento secondario in una sezione).
Prendiamo un esempio di un blocco eroe che ha 5 varianti. Si supponga di voler aggiungere la stessa descrizione per ogni variante del blocco, anziché duplicare library metadata con la descrizione in ogni sezione contenente le varianti. È invece possibile utilizzare default library metadata per applicare la stessa descrizione a ogni variante del blocco. Se decidi che una variante ha bisogno di una descrizione leggermente diversa, puoi aggiungere library metadata alla sezione contenente la variante e sovrascrivere la descrizione default library metadata quando viene riprodotta all'interno del plug-in dei blocchi.
Creazione di nomi e descrizioni di blocchi tramite i metadati della libreria
Per impostazione predefinita, il nome del blocco (con variante) verrà utilizzato per eseguire il rendering dell’elemento nel plug-in dei blocchi. Ad esempio, se il nome del blocco è columns (center, background), verrà utilizzato come etichetta quando viene eseguito il rendering nel plug-in dei blocchi. È possibile personalizzare questa sezione creando una sezione library metadata all'interno della stessa sezione del blocco. I metadati della libreria possono essere utilizzati anche per creare una descrizione del blocco e per aggiungere searchTags in modo da includere un alias per il blocco quando si utilizza la funzione di ricerca.
Esempio di blocco con nome e descrizione personalizzati
Contenuto
Visualizzazione
Blocchi automatici e contenuto predefinito
Il plug-in blocchi è in grado di eseguire il rendering di contenuto predefinito e blocchi automatici. Per ottenere questo risultato, è necessario inserire default content o autoblock in una sezione dedicata, che deve includere una tabella library metadata che definisce una proprietà name, come descritto in precedenza. Se nei metadati della libreria non viene specificato alcun nome, l'elemento verrà etichettato come "Elemento senza nome".
Blocchi composti da contenuto nelle sezioni successive
In alcune situazioni, gli sviluppatori possono voler creare un blocco con contenuti provenienti da sezioni successive. Questo modello è sconsigliato per i motivi indicati qui, ma se scegli di utilizzarlo il plug-in blocchi può eseguire il rendering di questi elementi utilizzando la proprietà include next sections in library metadata.
Modelli
I modelli consentono di raggruppare un intero documento in un unico elemento della raccolta di barre laterali. Per contrassegnare un documento come modello, impostare type su template in default library metadata.
> Importante, library metadata deve trovarsi nella propria sezione ed essere l'unico elemento secondario da considerare default library metadata.
Il supporto di metadata è auspicabile anche per i modelli. Per aggiungere una tabella di metadati al modello è possibile utilizzare un blocco Page metadata.
Quando il modello viene copiato, un metadata con i valori verrà aggiunto insieme al contenuto negli Appunti.
Configurazione del plug-in Sidekick
Poiché la libreria della barra laterale è ospitata sulla stessa origine del contenuto, è necessario creare una pagina HTML statica per caricare e configurare il contenuto.
1. Creare un file denominato library.html in tools/sidekick/;
2. Incolla il seguente codice in library.html.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, viewport-fit=cover"
/>
<meta name="Description" content="AEM Sidekick Library" />
<meta name="robots" content="noindex" />
<base href="/" />
<style>
html,
body {
margin: 0;
padding: 0;
font-family: sans-serif;
background-color: #ededed;
height: 100%;
}
helix-sidekick { display: none }
</style>
<title>Sidekick Library</title>
</head>
<body>
<script
type="module"
src="https://www.aem.live/tools/sidekick/library/index.js"
></script>
<script>
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
}
document.body.prepend(library)
</script>
</body>
</html>
Nel codice qui sopra viene caricata la libreria di barra laterale da aem.live, quindi viene creato un elemento sidekick-library personalizzato e aggiunto alla pagina. L'elemento sidekick-library accetta un oggetto config necessario per configurare la libreria della barra laterale.
Parametri di configurazione supportati
Il plug-in blocchi supporta le seguenti proprietà di configurazione che possono essere impostate utilizzando l’oggetto plug-in.
Parametri di configurazione del plug-in Blocks
Esempi
Codifica immagini
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
encodeImages: true,
}
}
}
Riquadri di visualizzazione personalizzati (forma breve)
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [600, 900],
}
}
}
Riquadri di visualizzazione personalizzati
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [
{
width: '599px',
label: 'Small',
icon: 'device-phone',
},
{
width: '899px',
label: 'Medium',
icon: 'device-tablet',
},
{
width: '100%',
label: 'Large',
icon: 'device-desktop',
default: true,
},
],
}
}
}
Colori intestazione tabella personalizzati
Puoi personalizzare il colore di sfondo e di primo piano dell’intestazione della tabella quando incolla un blocco, i metadati di sezione o i metadati copiati dal plug-in blocchi.
Gli stili predefiniti possono essere impostati in library.html utilizzando le variabili CSS.
<style>
:root {
--sk-block-table-background-color: #03A;
--sk-block-table-foreground-color: #fff;
--sk-section-metadata-table-background-color: #f30;
--sk-section-metadata-table-foreground-color: #000;
--sk-metadata-table-background-color: #000;
--sk-metadata-table-foreground-color: #fff;
}
</style>
Questi valori possono essere sostituiti utilizzando metadati della libreria.
> A seconda della combinazione di colori di sistema selezionata per il computer degli utenti (modalità scura), è possibile che i colori scelti vengano modificati nel tentativo di migliorare l'accessibilità.
Configurazione del plug-in personalizzato
L'esempio seguente definisce un plug-in tags nella configurazione. Le chiavi dell'oggetto plugins devono corrispondere al nome del plugin. Tutte le altre proprietà definite nell'oggetto plugin saranno disponibili per il plugin tramite l'argomento di contesto del metodo decorate.
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
tags: {
src: '/tools/sidekick/plugins/tags/tags.js',
foo: 'bar'
}
}
}
Librerie estese
In alcuni casi può essere utile unire due librerie a blocchi. Quando viene definita una libreria estesa, l'applicazione della libreria laterale unisce la libreria base e quella estesa in un unico elenco di librerie per gli autori.
L’esempio seguente definisce una libreria di base e una libreria estesa (su un’altra origine) che verranno unite alla libreria di base.
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
extends: 'https://main--repo--owner.hlx.live/tools/sidekick/library.json'
}
> Le intestazioni Access-Control-Allow-Origin dovranno essere impostate sui blocchi library.json e della libreria estesa per consentirne il caricamento nella libreria della barra laterale. Per ulteriori informazioni, consulta Intestazioni risposta HTTP personalizzate.
> A causa dei criteri di stessa origine applicati dai browser sugli iframe, al momento non è possibile caricare l’anteprima di un blocco esteso.
Installazione di Sidekick config.json
Quindi, affinché la libreria della barra laterale venga visualizzata nella barra laterale, è necessario creare un file di configurazione in tools/sidekick/config.json. Questo file di configurazione deve essere creato nel bus di codice e deve essere archiviato in github.
{
"project": "Example",
"plugins": [
{
"id": "library",
"title": "Library",
"environments": ["edit"],
"url": "/tools/sidekick/library.html",
"includePaths": ["**.docx**"]
}
]
}
La proprietà url nella configurazione del plug-in indica il percorso da cui la barra laterale deve caricare il plug-in. Deve puntare al file library.html creato in precedenza.
> La configurazione della barra laterale deve essere archiviata nel ramo main affinché il plug-in venga visualizzato nella barra laterale.
> Se il file tools/sidekick/config.json non esiste nell'archivio github, è necessario crearlo. Per ulteriori informazioni sulle opzioni di configurazione del plug-in per la barra laterale, vedi i documenti.
Considerazioni durante la creazione di blocchi predefiniti per la libreria
La libreria della barra laterale esegue il rendering dei blocchi recuperando prima la rappresentazione plain.html del blocco e quindi eliminandola da qualsiasi altro blocco nel contenuto (ad esempio, se la risposta contiene più varianti di un blocco). Richiede quindi la stessa pagina (senza .plain.html), sostituisce l'elemento main con il blocco rimosso e carica l'intero documento in un iframe utilizzando l'attributo srcdoc.
Utilizzo di window.location
Poiché il blocco viene caricato in un iframe utilizzando l'attributo srcdoc, l'istanza dell'oggetto window.location utilizzata dal codice Sites non conterrà i valori tipici previsti.
Esempio di oggetto window.location durante l'esecuzione nella libreria
{
"host": "",
"hostname": "",
"href": "about:srcdoc"
"origin": "null"
"pathname": "srcdoc"
"port": ""
"protocol": "about:"
}
Per questo motivo, se il blocco richiede l'utilizzo dell'oggetto window.location, è consigliabile aggiungere le seguenti funzioni al file scripts.js e importarle nella funzione per l'utilizzo.
/**
* Returns the true origin of the current page in the browser.
* If the page is running in a iframe with srcdoc, the ancestor origin is returned.
* @returns {String} The true origin
*/
export function getOrigin() {
const { location } = window;
return location.href === 'about:srcdoc' ? window.parent.location.origin : location.origin;
}
/**
* Returns the true of the current page in the browser.mac
* If the page is running in a iframe with srcdoc,
* the ancestor origin + the path query param is returned.
* @returns {String} The href of the current page or the href of the block running in the library
*/
export function getHref() {
if (window.location.href !== 'about:srcdoc') return window.location.href;
const { location: parentLocation } = window.parent;
const urlParams = new URLSearchParams(parentLocation.search);
return `${parentLocation.origin}${urlParams.get('path')}`;
}
Utilizzo di createOptimizedPicture in lib-aem
Anche la funzione createOptimizedPicture in lib-aem utilizza window.location.href. Se utilizzi questa funzione, ti consigliamo di spostarla in scripts.js e modificarla per utilizzare la funzione getHref() precedente.
Verifica della presenza della libreria della barra laterale
A volte può essere utile sapere se la pagina o il blocco è in esecuzione nella libreria della barra laterale. Per fare questo ci sono un paio di opzioni.
1. Controlla se window.location.href === 'about:srcdoc'
2. L'elemento main e l'elemento blocco conterranno la classe sidekick-library
Creazione di un plug-in
Lo sviluppo di un plug-in è simile alla costruzione di un blocco in AEM. Quando un utente prova a caricare il plug-in, la libreria di sidekick attiverà il metodo decorate() sul plug-in. Questo metodo riceve il contenitore per il rendering del plug-in e di tutti i dati inclusi nel foglio dei plug-in.
/**
* Called when a user tries to load the plugin
* @param {HTMLElement} container The container to render the plugin in
* @param {Object} data The data contained in the plugin sheet
* @param {String} query If search is active, the current search query
* @param {Object} context contains any properties set when the plugin was registered
*/
export async function decorate(container, data, query, context) {
// Render your plugin
}
> La funzione decorate() deve essere esportata dal plug-in.
Esportazione e ricerca predefinite plug-in
L’esportazione predefinita da un plug-in consente agli autori di personalizzare il nome del plug-in visualizzato nell’intestazione al momento del caricamento, nonché di attivare la funzionalità di ricerca all’interno della libreria della barra laterale.
export default {
title: 'Tags',
searchEnabled: true,
};
Quando la proprietà searchEnabled è true, l'intestazione della libreria visualizza un'icona di ricerca al caricamento del plug-in. Se l'utente avvia una ricerca immettendo una query, la funzione decorate() del plug-in verrà attivata nuovamente, questa volta con la stringa di ricerca passata nel parametro query della funzione decorate().
Componenti web del plug-in
Gli autori di plug-in possono utilizzare un set selezionato di componenti Web di Spectrum per la creazione di un plug-in personalizzato.
Sono disponibili i seguenti componenti di Spectrum
Sono inoltre disponibili le seguenti icone di Spectrum
Eventi plug-in
Gli autori di plug-in possono inviare eventi dal plug-in alla libreria laterale principale per visualizzare un caricatore o un messaggio popup.
Messaggi popup
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';
export async function decorate(container, data, query) {
// Show a toast message
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.TOAST, { detail: { message: 'Toast Shown!', variant: 'positive | negative' } }))
}
Mostra e nascondi caricatore
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';
export async function decorate(container, data, query) {
// Show loader
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.SHOW_LOADER))
...
// Hide loader
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.HIDE_LOADER))
}