¿Qué es la biblioteca de la barra de tareas?
La biblioteca de la barra de tareas es una extensión de la barra de tareas de AEM que permite a los desarrolladores crear herramientas controladas por la interfaz de usuario para los autores de contenido. Incluye un complemento de bloques integrado que puede mostrar una lista de todos los bloques a los autores de forma intuitiva, lo que elimina la necesidad de que los autores recuerden o busquen cada variación de un bloque. Los desarrolladores también pueden escribir sus propios complementos para la biblioteca de la barra de tareas.
¿Cómo se utiliza la biblioteca de Sidekick?
Los pasos siguientes detallan cómo configurar la biblioteca de la barra de tareas y el complemento de bloques.
Configuración de hoja de biblioteca
La biblioteca de la barra de tareas se rellena con los complementos y el contenido del complemento con una hoja.
1. Comience creando un directorio en sharepoint o gdrive donde desee almacenar el contenido de la biblioteca. Se recomienda almacenar el contenido en /tools/sidekick (o cualquier otro nombre) en la raíz del punto de montaje. Los siguientes pasos asumirán que el directorio se llama /tools/sidekick.
2. A continuación, cree un libro (un archivo de Excel) en el directorio /tools/sidekick llamado library (o cualquier otro nombre). Cada hoja del libro representa un complemento que la biblioteca Sidekick cargará. El nombre de la hoja determina el nombre del complemento que se cargará. Los datos contenidos en la hoja se pasarán al complemento cuando se carguen. El nombre de la hoja de complementos debe ir precedido de helix-. Por ejemplo, si desea cargar un complemento denominado tags, debe crear una hoja denominada helix-tags.
3. Para este tutorial crearemos una hoja para nuestro complemento blocks. Cree una hoja (o cambie el nombre de la hoja predeterminada), llámela `helix-blocks` y déjela vacía por ahora.
Complemento de bloques
La biblioteca Sidekick viene con un complemento blocks.
Configuración del complemento de bloques
Para generar contenido para el complemento de bloques, debe preparar un documento de Word independiente para cada bloque que desee incluir.
1. Cree un directorio dentro del directorio /tools/sidekick donde almacenará todas las variaciones de bloques. Por ejemplo, podría crear un directorio llamado blocks dentro de /tools/sidekick.
2. Para este ejemplo, supongamos que queremos definir todas las variaciones de un bloque denominado columns. Primero cree un documento de Word llamado columns dentro del directorio blocks y proporcione ejemplos de todas las variaciones del bloque columns. Después de cada variación del bloque, agregue un delimitador de sección.
3. Previsualizar y publicar el documento columns.
4. Abra el libro de biblioteca creado en la última sección, dentro de la hoja helix-blocks, y cree dos columnas denominadas name y path.
6. A continuación, debemos agregar una fila para nuestro bloque columns. Agregue el nombre del bloque en la primera columna y la dirección URL al documento que define las variaciones de bloque en la segunda columna. Por ejemplo, si desea agregar el bloque columns, puede crear una fila con el nombre Columns y la ruta de acceso /tools/sidekick/blocks/columns. Para que la biblioteca funcione en entornos (página, activo, prod), no debe utilizar una URL absoluta para la columna de ruta.
7. Previsualizar y publicar el libro library.
> Dado que los bloques de ejemplo se están publicando, debe usar metadatos en bloque para excluir el contenido de /tools/** de la indización.
Ejemplo library.xlsx
Metadatos de biblioteca
Los complementos de bloques admiten un tipo especial de bloque denominado library metadata, que proporciona a los desarrolladores la forma de indicarle al complemento de bloques alguna información sobre el bloque o cómo se debe representar.
Opciones de metadatos de biblioteca compatibles
Metadatos de biblioteca predeterminados frente a metadatos de biblioteca
Existen dos tipos de library metadata. Los metadatos de biblioteca que se encuentran dentro de una sección que contiene el bloque, o default library metadata que se aplica al documento en su totalidad y que se encuentran en una sección por sí solos (un bloque denominado library metadata como el único elemento secundario de una sección).
Veamos un ejemplo de un bloque a pantalla completa que tiene 5 variantes. Supongamos que desea agregar la misma descripción para cada variación del bloque en lugar de duplicar library metadata con la descripción en cada sección que contenga las variaciones. En su lugar, podría usar default library metadata para aplicar la misma descripción a cada variación del bloque. Si decide que una variación necesita realmente una descripción ligeramente diferente, podría agregar library metadata a la sección que contiene la variación y anularía la descripción predeterminada library metadata cuando se procese dentro del complemento de bloques.
Creación de nombres y descripciones de bloques mediante metadatos de biblioteca
De forma predeterminada, el nombre del bloque (con variación) se utilizará para procesar el elemento en el complemento de bloques. Por ejemplo, si el nombre del bloque es columns (center, background), ese nombre se utilizará como etiqueta cuando se represente en el complemento de bloques. Esto se puede personalizar creando una sección library metadata dentro de la misma sección que el bloque. Los metadatos de biblioteca también se pueden usar para crear una descripción del bloque y para agregar searchTags a fin de incluir un alias para el bloque al usar la característica de búsqueda.
Bloque de ejemplo con nombre y descripción personalizados
Contenido
Pantalla
Bloques automáticos y contenido predeterminado
El complemento de bloques puede procesar contenido predeterminado y autoblocks. Para conseguirlo, es necesario colocar su default content o autoblock dentro de una sección dedicada, que debe incluir una tabla library metadata que defina una propiedad name, como se describió anteriormente. Si no se especifica ningún nombre en los metadatos de la biblioteca, el elemento se etiquetará como "Elemento sin nombre".
Bloques compuestos de contenido en secciones subsiguientes
Hay situaciones en las que los desarrolladores pueden querer que un bloque consista en contenido de secciones posteriores. No se recomienda este patrón por las razones indicadas aquí, pero si elige usarlo, el complemento de bloques puede procesar estos elementos mediante la propiedad include next sections en library metadata.
Plantillas
Las plantillas son una forma de agrupar todo un documento en un solo elemento de la biblioteca de la barra de tareas. Para marcar un documento como un conjunto de plantillas type a template en default library metadata.
> Importante: library metadata debe estar en su propia sección y ser el único elemento secundario que se considere default library metadata.
También es deseable admitir metadata para las plantillas. Para agregar una tabla de metadatos a la plantilla, puede utilizar un bloque Page metadata.
Cuando se copie la plantilla, se agregará un(a) metadata con los valores junto con el contenido al portapapeles.
Configuración del complemento de Sidekick
Dado que la biblioteca de la barra de tareas está alojada en el mismo origen que el contenido, es necesario crear una página estática de HTML para cargar y configurar el contenido.
1. Crear un archivo llamado library.html en tools/sidekick/;
2. Pegue el siguiente código en 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>
En el código anterior, cargamos la biblioteca de la barra de tareas de aem.live y, a continuación, creamos un elemento sidekick-library personalizado y lo agregamos a la página. El elemento sidekick-library acepta un objeto config necesario para configurar la biblioteca de la barra de tareas.
Parámetros de configuración admitidos
El complemento de bloques admite las siguientes propiedades de configuración que se pueden establecer con el objeto plugins.
Parámetros de configuración del complemento de bloques
Ejemplos
Codificación de imágenes
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
encodeImages: true,
}
}
}
Ventanillas personalizadas (forma corta)
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [600, 900],
}
}
}
Ventanillas personalizadas
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,
},
],
}
}
}
Colores de encabezado de tabla personalizados
Puede personalizar el fondo del encabezado de tabla y el color de primer plano al pegar un bloque, metadatos de sección o metadatos que se copiaron del complemento de bloques.
Los estilos predeterminados se pueden establecer en library.html mediante 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>
Estos valores se pueden sobrescribir usando metadatos de biblioteca.
> Dependiendo del esquema de colores del sistema seleccionado para el equipo de los usuarios (modo oscuro), Word puede modificar los colores elegidos en un intento de mejorar la accesibilidad.
Configuración del complemento personalizado
El ejemplo siguiente define un complemento tags en la configuración. Las claves del objeto plugins deben coincidir con el nombre del complemento. Cualquier otra propiedad definida en el objeto plugin estará disponible para el complemento a través del argumento context del método 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'
}
}
}
Bibliotecas extendidas
En algunos casos, puede ser deseable combinar dos bibliotecas de bloques. Cuando se define una biblioteca extendida, la aplicación de biblioteca de la barra de tareas combinará la biblioteca base y la biblioteca extendida en una sola lista de bibliotecas para los autores.
El ejemplo siguiente define una biblioteca base y una biblioteca extendida (en otro origen) que se combinarán en la biblioteca 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'
}
> Los encabezados Access-Control-Allow-Origin deberán establecerse en library.json y bloques de la biblioteca extendida para que se carguen en la biblioteca de la barra de tareas. Consulte Encabezados de respuesta HTTP personalizados para obtener más información.
> Debido a las políticas del mismo origen que aplican los exploradores en los iframes, no se puede cargar una vista previa de un bloque extendido en este momento.
Configuración de Sidekick config.json
A continuación, para que la biblioteca de la barra de tareas aparezca en la barra de tareas, se debe crear un archivo de configuración en tools/sidekick/config.json. Este archivo de configuración debe crearse en el bus de código y registrarse en github.
{
"project": "Example",
"plugins": [
{
"id": "library",
"title": "Library",
"environments": ["edit"],
"url": "/tools/sidekick/library.html",
"includePaths": ["**.docx**"]
}
]
}
La propiedad url de la configuración del complemento indica la ubicación desde la que la barra de tareas debe cargar el complemento. Esto debería apuntar al archivo library.html que creamos anteriormente.
> La configuración de la barra de tareas debe registrarse en la rama main para que el complemento aparezca en la barra de tareas.
> Si el archivo tools/sidekick/config.json no existe en el repositorio de github, se debe crear. Para obtener más información sobre las opciones de configuración del complemento de la barra de tareas, consulte los documentos.
Consideraciones al crear bloques para la biblioteca
La biblioteca de la barra de tareas procesa los bloques recuperando primero la representación plain.html del bloque y, a continuación, lo elimina de cualquier otro bloque del contenido (por ejemplo, si hay varias variaciones de un bloque en la respuesta). A continuación, solicita la misma página (sin .plain.html) y reemplaza el elemento main por el bloque eliminado y carga todo el documento en un elemento iframe mediante el atributo srcdoc.
Uso de window.location
Dado que el bloque se carga en un iframe mediante el atributo srcdoc, la instancia del objeto window.location que usa el código de sitios no contendrá los valores típicos que esperaría ver.
Ejemplo de objeto window.location al ejecutarse en la biblioteca
{
"host": "",
"hostname": "",
"href": "about:srcdoc"
"origin": "null"
"pathname": "srcdoc"
"port": ""
"protocol": "about:"
}
Por este motivo, si el bloque requiere el uso del objeto window.location, se recomienda agregar las siguientes funciones al archivo scripts.js e importarlas a su función para su uso.
/**
* 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')}`;
}
Uso de createOptimizedPicture en lib-aem
La función createOptimizedPicture de lib-aem también usa window.location.href. Si utiliza esta función, le recomendamos que la mueva a scripts.js y la modifique para que utilice la función getHref() anterior.
Comprobación de la presencia de la biblioteca de la barra de tareas
A veces, es posible que desee saber si la página o el bloque se está ejecutando en la biblioteca de la barra de tareas. Para hacer esto hay un par de opciones.
1. Comprobar si window.location.href === 'about:srcdoc'
2. El elemento main y el elemento de bloque contendrán la clase sidekick-library
Creación de un complemento
Desarrollar un complemento es similar a construir un bloque en AEM. Una vez que un usuario intente cargar el complemento, la biblioteca de la barra de tareas almacenará en déclencheur el método decorate() en el complemento. Este método recibe el contenedor para procesar el complemento y cualquier dato incluido en la hoja de complementos.
/**
* 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 función decorate() debe exportarse desde el complemento.
Exportación y búsqueda predeterminadas del complemento
La exportación predeterminada desde un complemento permite a los autores personalizar el nombre del complemento que se muestra en el encabezado al cargar, así como activar la funcionalidad de búsqueda en la biblioteca de la barra de tareas.
export default {
title: 'Tags',
searchEnabled: true,
};
Cuando la propiedad searchEnabled es verdadera, el encabezado de la biblioteca mostrará un icono de búsqueda al cargar el complemento. Si el usuario inicia una búsqueda al escribir una consulta, la función decorate() del complemento se activará de nuevo, esta vez con la cadena de búsqueda pasada en el parámetro de consulta de la función decorate().
Componentes web del complemento
Los autores de complementos pueden utilizar un conjunto selecto de componentes web de Spectrum al crear un complemento personalizado.
Los siguientes componentes de Spectrum están disponibles
También están disponibles los siguientes iconos de Spectrum
Eventos de complemento
Los autores de complementos pueden enviar eventos desde su complemento a la biblioteca de la barra de tareas principal para mostrar un cargador o mostrar un mensaje de mensaje.
Mensajes de Toast
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' } }))
}
Mostrar y ocultar cargador
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))
}