Desarrollo para Sidekick

El objetivo de este documento es explicar cómo los desarrolladores pueden interactuar con la barra de tareas y cómo se puede personalizar a nivel de proyecto.

Eventos

La barra de tareas emite los siguientes eventos:

Se puede encontrar la carga útil de un evento en la propiedad event.detail.

Escucha de eventos

En el código de su proyecto (por ejemplo, en /scripts/scripts.js), puede reaccionar a los eventos de la barra de tareas de la siguiente manera (reemplace foo por el nombre del evento que desea escuchar):

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

Personalización de Sidekick

Puede personalizar la barra de tareas del proyecto. Puede agregar un archivo de configuración /tools/sidekick/config.json al repositorio de GitHub del proyecto o usar el servicio de configuración.

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

Para ver todas las opciones de configuración disponibles, consulte config schema. A continuación se indican algunos conceptos básicos para comenzar:

Plugins

Los complementos le permiten agregar funciones personalizadas a la barra de tareas, lo que mejora la experiencia de los usuarios.

Propiedades de complemento comunes

Las siguientes propiedades se aplican a todos los tipos de complementos:

Complementos basados en URL

Puede especificar un(a) url que se abrirá en una ficha nueva cuando se haga clic en el botón del complemento:

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

Complementos basados en eventos

También puede especificar el nombre de un event que se activará cuando se haga clic en el botón del complemento. Esto permite ejecutar código JavaScript personalizado en el contexto de la página al escuchar el evento en el elemento de la barra de tareas. Los eventos personalizados tendrán un prefijo custom:. Para su comodidad, el evento personalizado enviado contiene una copia del estado actual de la barra de tareas.

Nota: Los complementos basados en eventos sólo se pueden usar en los entornos siguientes: Desarrollo, Vista previa, Activo y Producción. No se puede ejecutar el código personalizado en Editar o Administración.

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

En el código del proyecto (por ejemplo, en /scripts/scripts.js), puede reaccionar al evento de la siguiente manera:

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

Tipos de complementos especiales

Complementos de paleta

Las paletas son variantes de los complementos basados en URL que cargan la URL configurada en línea en lugar de abrir una nueva pestaña.

El siguiente ejemplo crea una paleta estándar en la parte inferior izquierda de la ventana:

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

Si desea cambiar el tamaño y la posición de la paleta, utilice paletteRect:

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

Complementos de contenedor

Los contenedores le permiten agrupar los complementos y ahorrar espacio en la barra de herramientas. Al hacer clic en un complemento de contenedor, simplemente se alterna su lista desplegable; no puede tener su propia URL o acción de evento.

En el ejemplo siguiente se crea un contenedor denominado "Tools" y se coloca un complemento "Foo" en él:

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

Complementos de distintivo

Las insignias permiten agregar etiquetas a la barra de tareas en ciertas condiciones. Se representan en la parte derecha de la barra de herramientas. Las insignias tienen un mero propósito decorativo y no se puede hacer clic en ellas.

El siguiente ejemplo agrega un distintivo "Escenario" a la barra de tareas en el entorno de vista previa:

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

URL de edición personalizadas

Si el proyecto no usa SharePoint o Google Drive como fuente de contenido, puedes indicarle a la barra de tareas cómo vincular a tu entorno de edición personalizado cuando el usuario haga clic en Editar.

Estas son las opciones de configuración disponibles:

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

Vistas especiales

Puede especificar una vista especial a la que redirigir la barra de tareas cuando la dirección URL de la pestaña actual coincida con un patrón determinado. Esto puede ayudarle a proporcionar una experiencia de usuario perfecta en diferentes tipos de medios y también permite la ejecución de código personalizado (complementos basados en eventos). La dirección URL del recurso original estará disponible en un parámetro de consulta url.

Las propiedades path y viewer son obligatorias. Opcionalmente, puede especificar un(a) title que se mostrará en la parte superior y puede proporcionar títulos localizados en un objeto titleI18n:

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

En la ruta especificada por viewer, agregue un archivo HTML al repositorio de GitHub, por ejemplo:

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

Añada un archivo CSS opcional en el mismo directorio y un archivo JS con la lógica personalizada, por ejemplo:

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

Flujo de trabajo de desarrollo

Los siguientes flujos de trabajo están diseñados para el desarrollo de tareas secundarias independientes a fin de evitar interrupciones no intencionadas para los autores del sitio de producción:

Uso de una copia del sitio

Si la configuración de su sitio está almacenada en el Servicio de configuración, puede usar copias temporales del sitio para el desarrollo de la barra de tareas:

Nota: Al usar la barra de tareas en un entorno de edición (Google Drive o Microsoft Sharepoint), cargará la configuración del sitio original de forma predeterminada. Si desea que la barra de tareas le permita elegir qué configuración cargar, primero agregue el nuevo sitio a la barra de tareas desde la vista previa o la dirección URL activa. Ahora la barra de tareas mostrará un selector con todos los sitios coincidentes.

Uso de una rama del repositorio

Si la configuración de su sitio no está almacenada en el Servicio de configuración, puede usar una rama en GitHub para el desarrollo de la barra de tareas:

Precaución: No confirmar nunca directamente la rama main en el repositorio original. Cree siempre una rama y pida una revisión de sus cambios mediante una solicitud de extracción antes de combinarlos en main.

Nota: Al usar la barra de tareas en un entorno de edición (Google Drive o Microsoft Sharepoint), cargará la configuración del sitio original de forma predeterminada. Si desea que la barra de tareas le permita elegir qué configuración cargar, primero agregue el nuevo sitio a la barra de tareas desde la vista previa o la dirección URL activa. Ahora la barra de tareas mostrará un selector con todos los sitios coincidentes.