Qu’est-ce que la bibliothèque sidekick ?
La bibliothèque sidekick est une extension du sidekick AEM qui permet aux équipes de développement de créer des outils pilotés par l’interface utilisateur pour les auteurs et autrices de contenu. Elle comprend un plug-in de blocs intégré qui peut afficher intuitivement une liste de tous les blocs pour les auteurs et autrices, ce qui leur évite de mémoriser ou de rechercher chaque variation d’un bloc. Les équipes de développement peuvent également écrire leurs propres plug-ins pour la bibliothèque sidekick.
Comment utiliser la bibliothèque Sidekick ?
Les étapes ci-dessous expliquent comment configurer la bibliothèque du sidekick et le plug-in Blocs.
Configuration feuille bibliothèque
La bibliothèque du sidekick est renseignée avec vos modules externes et le contenu du module externe à l’aide d’une feuille.
1. Commencez par créer un répertoire dans sharepoint ou gdrive où vous souhaitez stocker le contenu de la bibliothèque. Nous vous recommandons de stocker le contenu dans /tools/sidekick (ou tout autre nom) à la racine du point de montage. Les étapes suivantes supposent que le répertoire est appelé /tools/sidekick.
2. Créez ensuite un classeur (fichier Excel) dans le répertoire /tools/sidekick appelé library (ou tout autre nom). Chaque feuille du classeur représente un module externe qui sera chargé par la bibliothèque Sidekick. Le nom de la feuille détermine le nom du module externe qui sera chargé. Toutes les données contenues dans la feuille seront transmises au plug-in lors du chargement. Le nom de la feuille du plug-in doit être précédé de helix-. Par exemple, si vous souhaitez charger un module externe appelé tags, vous devez créer une feuille nommée helix-tags.
3. Pour ce tutoriel, nous allons créer une feuille pour notre plug-in blocks. Créez une feuille (ou renommez la feuille par défaut) et appelez-la `helix-blocs`, puis laissez-la vide pour l’instant.
Plug-in Blocks
La bibliothèque Sidekick est fournie avec un plug-in blocks.
Configuration du plug-in Blocks
Pour générer du contenu pour le module externe Blocs, vous devez préparer un document Word distinct pour chaque bloc que vous souhaitez inclure.
1. Créez un répertoire à l’intérieur du répertoire /tools/sidekick dans lequel vous stockerez toutes les variations de bloc. Par exemple, vous pouvez créer un répertoire appelé blocks à l’intérieur de /tools/sidekick.
2. Pour cet exemple, supposons que nous voulions définir toutes les variations d’un bloc appelé columns. Créez d’abord un document Word appelé columns dans le répertoire blocks et fournissez des exemples de toutes les variations du bloc columns. Après chaque variante du bloc, ajoutez un délimiteur de section.
3. Prévisualisez et publiez le document columns.
4. Ouvrez le classeur de bibliothèque créé dans la dernière section, à l’intérieur de la feuille de helix-blocks, créez deux colonnes appelées name et path.
6. Nous devons ensuite ajouter une ligne pour notre bloc de columns. Ajoutez le nom du bloc dans la première colonne et l’URL au document qui définit les variations du bloc dans la seconde colonne. Par exemple, si vous souhaitez ajouter le bloc columns, vous pouvez créer une ligne avec le nom Columns et le chemin d’accès /tools/sidekick/blocks/columns. Pour que la bibliothèque fonctionne dans plusieurs environnements (page, ligne, production), vous ne devez pas utiliser d’URL absolue pour la colonne de chemin d’accès.
7. Prévisualisez et publiez le classeur library.
> Comme les exemples de blocs sont en cours de publication, vous devez utiliser métadonnées en bloc pour exclure le contenu de /tools/** de l’indexation.
Exemple library.xlsx
Métadonnées de bibliothèque
Les modules externes de blocs prennent en charge un type spécial de bloc appelé library metadata, qui permet aux développeurs d’indiquer au module externe de blocs certaines informations sur le bloc ou sur la manière dont il doit être rendu.
Options de métadonnées de bibliothèque prises en charge
Métadonnées de bibliothèque par défaut par rapport aux métadonnées de bibliothèque
Il existe deux types de library metadata. Métadonnées de bibliothèque qui résident dans une section contenant le bloc, ou library metadata par défaut qui s’applique au document dans son ensemble et qui réside dans une section à part entière (bloc appelé library metadata en tant qu’enfant unique d’une section).
Prenons un exemple de bloc de héros qui comporte 5 variantes. Supposons que vous souhaitiez ajouter la même description pour chaque variation du bloc, plutôt que de dupliquer la library metadata avec la description dans chaque section contenant les variations. Vous pouvez plutôt utiliser l’library metadata par défaut pour appliquer la même description à chaque variation du bloc. Si vous décidez qu’une variation nécessite en fait une description légèrement différente, vous pouvez ajouter des library metadata à la section contenant la variation et elle remplacera la description library metadata par défaut lors de son rendu dans le plug-in Blocs.
Création de noms et de descriptions de blocs à l’aide des métadonnées de bibliothèque
Par défaut, le nom du bloc (avec variation) est utilisé pour effectuer le rendu de l’élément dans le plug-in des blocs. Par exemple, si le nom du bloc est columns (center, background), il est utilisé comme libellé lors de son rendu dans le plug-in Blocs . Cette opération peut être personnalisée en créant une section library metadata dans la même section que le bloc. Les métadonnées de bibliothèque peuvent également être utilisées pour créer une description du bloc et pour ajouter des searchTags afin d’inclure un alias pour le bloc lors de l’utilisation de la fonction de recherche.
Exemple de bloc avec nom et description personnalisés
Contenu
Affichage
Blocages automatiques et contenu par défaut
Le plug-in Blocs peut effectuer le rendu contenu par défaut et blocs automatiques. Pour ce faire, il est nécessaire de placer votre default content ou votre autoblock dans une section dédiée, qui doit inclure un tableau library metadata définissant une propriété name, comme décrit précédemment. Si aucun nom n’est spécifié dans les métadonnées de la bibliothèque, l’élément est étiqueté comme « Élément sans nom ».
Blocs composés de contenu dans les sections suivantes
Dans certains cas, les développeurs peuvent vouloir qu’un bloc soit constitué de contenu provenant des sections suivantes. Ce modèle est déconseillé pour les raisons indiquées ici, mais si vous choisissez de l’utiliser, le plug-in Blocs peut effectuer le rendu de ces éléments à l’aide de la propriété include next sections dans library metadata.
Modèles
Les modèles permettent de regrouper un document entier en un seul élément dans la bibliothèque du sidekick. Pour marquer un document en tant que modèle, définissez type sur template dans default library metadata.
> Important, le library metadata doit se trouver dans sa propre section et être le seul enfant à être considéré comme default library metadata.
La prise en charge des metadata est également souhaitable pour les modèles. Pour ajouter un tableau de métadonnées au modèle, vous pouvez utiliser un bloc de Page metadata.
Lorsque le modèle est copié, un metadata avec les valeurs est ajouté avec le contenu dans le presse-papiers.
Configuration du plug-in Sidekick
La bibliothèque de sidekick étant hébergée sur la même origine que le contenu, une page HTML statique doit être créée pour charger et configurer le contenu.
1. Créez un fichier appelé library.html dans tools/sidekick/ ;
2. Collez le code suivant dans 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>
Dans le code ci-dessus, nous chargeons la bibliothèque de sidekick à partir de aem.live, puis nous créons un élément de sidekick-library personnalisé et l’ajoutons à la page. L’élément sidekick-library accepte un objet config requis pour configurer la bibliothèque du sidekick.
Paramètres de configuration pris en charge
Le module externe de blocs prend en charge les propriétés de configuration suivantes, qui peuvent être définies à l’aide de l’objet plugins.
Bloque les paramètres de configuration du plug-in
Exemples
Codage d’images
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
encodeImages: true,
}
}
}
Fenêtres d’affichage personnalisées (forme abrégée)
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [600, 900],
}
}
}
Fenêtres d’affichage personnalisées
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,
},
],
}
}
}
Couleurs d’en-tête de tableau personnalisées
Vous pouvez personnaliser la couleur d’arrière-plan et de premier plan de l’en-tête du tableau lors du collage d’un bloc, de métadonnées de section ou de métadonnées copiés à partir du plug-in Blocs.
Les styles par défaut peuvent être définis dans library.html à l’aide de variables 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>
Ces valeurs peuvent être remplacées à l’aide de métadonnées de bibliothèque.
> En fonction du jeu de couleurs système sélectionné pour l'ordinateur des utilisateurs (mode sombre), Word peut modifier les couleurs sélectionnées dans le but d'améliorer l'accessibilité.
Configuration du plug-in personnalisé
L’exemple ci-dessous définit un module externe tags dans la configuration . Les clés de l’objet plugins doivent correspondre au nom du plug-in. Toute autre propriété définie dans l’objet plugin sera disponible pour le plug-in via l’argument contextuel de la méthode decoration.
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
tags: {
src: '/tools/sidekick/plugins/tags/tags.js',
foo: 'bar'
}
}
}
Bibliothèques étendues
Dans certains cas, la fusion de deux bibliothèques de blocs peut être souhaitable. Lorsqu’une bibliothèque étendue est définie, l’application de bibliothèque du sidekick fusionne la bibliothèque de base et la bibliothèque étendue en une seule liste de bibliothèque pour les auteurs.
L’exemple ci-dessous définit une bibliothèque de base et une bibliothèque étendue (sur une autre origine) qui seront fusionnées dans la bibliothèque de 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'
}
> Les en-têtes Access-Control-Allow-Origin doivent être définis sur les library.json et blocs de la bibliothèque étendue pour qu’ils puissent se charger dans la bibliothèque du sidekick. Voir En-têtes de réponse HTTP personnalisés pour plus d’informations.
> En raison des politiques de même origine appliquées par les navigateurs sur les iFrames, l’aperçu d’un bloc étendu ne peut pas être chargé pour le moment.
Configuration de Sidekick config.json
Ensuite, pour que la bibliothèque du sidekick apparaisse dans le sidekick, un fichier de configuration doit être créé à l’adresse tools/sidekick/config.json. Ce fichier de configuration doit être créé dans le bus de code et doit être archivé dans github.
{
"project": "Example",
"plugins": [
{
"id": "library",
"title": "Library",
"environments": ["edit"],
"url": "/tools/sidekick/library.html",
"includePaths": ["**.docx**"]
}
]
}
La propriété url dans la configuration du plug-in indique l’emplacement à partir duquel le sidekick doit charger le plug-in. Cela devrait pointer vers le fichier library.html que nous avons précédemment créé.
> La configuration du sidekick doit être archivée dans la branche main pour que le plug-in apparaisse dans le sidekick.
> Si le fichier tools/sidekick/config.json n’existe pas dans votre référentiel github, il doit être créé. Pour plus d’informations sur les options de configuration du plug-in sidekick, consultez la documentation.
Remarques concernant la création de blocs pour la bibliothèque
La bibliothèque du sidekick effectue le rendu des blocs en récupérant d’abord le rendu plain.html du bloc, puis en le supprimant de tout autre bloc dans le contenu (par exemple, si la réponse contient plusieurs variations d’un bloc). Il demande ensuite la même page (sans .plain.html) et remplace l’élément main par le bloc supprimé et charge l’intégralité du document dans un iframe à l’aide de l’attribut srcdoc.
Utilisation des window.location
Puisque le bloc est chargé dans un iframe à l’aide de l’attribut srcdoc, l’instance de l’objet window.location utilisé par votre code de sites ne contiendra pas les valeurs standard attendues.
Exemple d’objet window.location lors de l’exécution dans la bibliothèque
{
"host": "",
"hostname": "",
"href": "about:srcdoc"
"origin": "null"
"pathname": "srcdoc"
"port": ""
"protocol": "about:"
}
Pour cette raison, si votre bloc nécessite l'utilisation de l'objet window.location, nous vous recommandons d'ajouter les fonctions suivantes à votre fichier scripts.js et de les importer dans votre fonction pour les utiliser.
/**
* 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')}`;
}
Utilisation de createOptimizedPicture dans lib-aem
La fonction createOptimizedPicture dans lib-aem utilise également 🔗 window.location.href . Si vous utilisez cette fonction, nous vous recommandons de la déplacer dans scripts.js et de la modifier pour utiliser la fonction getHref() ci-dessus.
Vérification de la présence de la bibliothèque du sidekick
Parfois, vous pouvez vouloir savoir si la page ou le bloc est en cours d’exécution dans la bibliothèque du sidekick. Pour ce faire, il existe plusieurs options.
1. Vérifier si window.location.href === 'about:srcdoc'
2. L’élément main et l’élément de bloc contiennent la classe sidekick-library
Création d’un plug-in
Le développement d’un module externe est similaire à la construction d’un bloc dans AEM. Une fois qu’un utilisateur tente de charger le plug-in, la bibliothèque du sidekick déclenche la méthode decorate() sur votre plug-in. Cette méthode reçoit le conteneur pour effectuer le rendu du plug-in et de toutes les données incluses dans la feuille des plug-ins.
/**
* 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 fonction decorate() doit être exportée à partir du plug-in .
Exportation et recherche par défaut du plug-in
L’exportation par défaut à partir d’un module externe permet aux auteurs de personnaliser le nom du module externe affiché dans l’en-tête au chargement et d’activer la fonctionnalité de recherche dans la bibliothèque du sidekick.
export default {
title: 'Tags',
searchEnabled: true,
};
Lorsque la propriété searchEnabled est définie sur true, l’en-tête de la bibliothèque affiche une icône de recherche lors du chargement du module externe. Si l’utilisateur ou l’utilisatrice lance une recherche en saisissant une requête, la fonction de decorate() du module externe sera déclenchée à nouveau, cette fois avec la chaîne de recherche transmise dans le paramètre de requête de la fonction de decorate().
Composants web de plug-in
Les auteurs de plug-ins peuvent utiliser un ensemble sélectionné de composants web de Spectrum lors de la création d’un plug-in personnalisé.
Les composantes suivantes du spectre sont disponibles
Les icônes suivantes de Spectrum sont également disponibles
Événements de plug-in
Les auteurs de plug-ins peuvent distribuer des événements de leur plug-in à la bibliothèque du sidekick parent afin d’afficher un chargeur ou un message toast.
Messages toasts
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' } }))
}
Afficher et masquer le chargeur
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))
}