Anatomía de un proyecto
En este documento se describe qué aspecto típico debe tener un proyecto desde el punto de vista del código. Antes de leer este documento, familiarícese con el documento Introducción: tutorial para desarrolladores.
Git y GitHub
Una de nuestras filosofías definitorias es que es más fácil permitir que los usuarios trabajen con las herramientas con las que están familiarizados. La abrumadora mayoría de los desarrolladores administran su código en sistemas basados en Git, por lo que solo tiene sentido permitir que los desarrolladores trabajen con Git para administrar e implementar su código.
Estamos utilizando un enfoque sin compilaciones que se ejecuta directamente desde su repositorio de GitHub. Después de instalar el bot de AEM GitHub en su repositorio, los sitios web se crean automáticamente para cada una de sus ramas para la vista previa de contenido en https://<branch>--<repo>--<owner>.aem.page/ y el sitio de producción en https://<branch>--<repo>--<owner>.aem.live/ para el contenido publicado.
Todos los recursos que coloque en su repositorio de GitHub están disponibles en su sitio web, por lo que un archivo del repositorio de GitHub en la rama principal de /scripts/scripts.js estará disponible en https://main--<repo>--<owner>.aem.page/scripts/scripts.js
Esto debería ser muy intuitivo. Hay pocos archivos "especiales" que Adobe Experience Manager utilice para conectar el contenido al sitio web.
Recomendamos encarecidamente que los repositorios se mantengan públicos en GitHub para fomentar la comunidad. Para un sitio web público no hay necesidad de mantener el código oculto, ya que se sirve a los navegadores de su sitio web.
Notas importantes:
- La combinación
<branch>--<repo>--<owner>no debe exceder los 63 caracteres (incluyendo guiones/guiones). Es una restricción de nombre de subdominio. branch,repoyownerno pueden contener--.
Archivos de configuración
Hay algunos archivos en su repositorio de GitHub que tienen un significado especial para AEM y que se procesan de una manera especial. Estos archivos se encuentran en el directorio raíz del repositorio.
La conexión de contenido: fstab.yaml
Como puede haber visto en la guía de introducción, el archivo fstab.yaml sirve como conexión a las carpetas de Google Drive o SharePoint que contienen su contenido. Este archivo se utiliza como indicador de cómo el código del repositorio de GitHub se combina con el contenido del origen de contenido.
Más allá de proporcionar la conexión con el contenido, fstab.yaml también proporciona una función de asignación de carpetas que le permite asignar "rutas" sin extensión a un fragmento determinado de contenido o a HTML estático.
El punto de entrada: head.html
El archivo head.html es el punto de extensión más importante para influir en el marcado del contenido. La manera más fácil de verlo es que este archivo se inserta en el servidor como parte de la etiqueta HTML <head> y se combina con los metadatos procedentes del contenido.
head.html debe permanecer sin cambios en gran medida con respecto a la plantilla y solo hay muy pocas razones legítimas en un proyecto normal para realizar cambios. Estas incluyen la reasignación del proyecto a una URL base diferente con el fin de exponer el proyecto en una carpeta diferente a la carpeta raíz del dominio en su CDN o para admitir exploradores heredados que generalmente requieren scripts que no se cargan como módulos.
Se recomienda no agregar tecnología de marketing como Adobe Web SDK, Google Tag Manager u otros scripts de terceros al archivo head.html debido a impactos en el rendimiento. Tampoco se recomienda agregar scripts o estilos en línea a head.html por motivos de administración de código y rendimiento. Consulte la sección Scripts y estilos más abajo para obtener más información sobre la administración de scripts y estilos.
Consulte los siguientes ejemplos.
No encontrado: 404.html
Para crear una respuesta 404 personalizada, coloque un archivo 404.html en la raíz del repositorio de github. Esto se proporcionará en cualquier dirección URL que no se asigne a un recurso existente en contenido o código y reemplaza el cuerpo de la respuesta minimalista predeterminada 404.
404 puede imitar el marcado de una página existente, incluido el código del sitio, con pies de página de navegación, etc., o puede tener un aspecto completamente diferente.
Consulte los siguientes ejemplos.
No servir: .hlxignore
Hay algunos archivos en su repositorio que no deben entregarse desde su sitio web, ya sea porque desea mantenerlos privados o porque no son relevantes para el envío del sitio web (por ejemplo, pruebas, herramientas de compilación, artefactos de compilación, etc.) y no necesitan ser observados por el bot de AEM. Puede agregarlos a un archivo .hlxignore en el mismo formato que el archivo .gitignore conocido.
Consulte el siguiente ejemplo.
Domine los bots: robots.txt
Un archivo de robots.txt suele ser un archivo normal que se proporciona como cabría esperar en el sitio web de producción en su propio dominio. Para proteger la vista previa y el sitio de origen de la indización, los sitios .page y .live ofrecerán un archivo robots.txt que deshabilita todos los robots en lugar del archivo robots.txt de su repositorio.
Consulte los siguientes ejemplos.
Consulta e indexación: helix-query.yaml
Existe una función de indexación flexible que le permite realizar un seguimiento de todas las páginas de contenido de forma práctica como una hoja de cálculo. Esta función se utiliza a menudo para mostrar listas o fuentes de páginas, así como para filtrar y ordenar contenido en un sitio web. Consulte el documento Indexación para obtener más información.
Consulte los siguientes ejemplos.
Automatice su mapa del sitio: helix-sitemap.yaml
Se pueden crear automáticamente mapas del sitio complejos cada vez que los autores publiquen contenido nuevo, incluidas asignaciones flexibles de hreflang donde sea necesario. Esta funcionalidad generalmente se basa en la función de indexación.
Consulte este problema de GitHub para ver las opciones de configuración de mapa del sitio.
Consulte los siguientes ejemplos.
Estructura de carpetas y archivos más utilizada
Más allá de los archivos que tratan como archivos especiales o de configuración, hay una estructura usada con frecuencia que se expresa en Repo de plantillas.
Las carpetas comunes siguientes suelen encontrarse en el directorio raíz de un repositorio de proyecto, pero en los casos en que AEM gestiona solo una parte de un sitio web, a menudo se mueven a una subcarpeta para reflejar la asignación de la ruta de origen en una CDN.
Esto significa que en un caso en el que por ejemplo solo /en/blog/ se asigna inicialmente a AEM desde la CDN, todas las estructuras de carpetas por debajo (p. ej., /scripts, /styles, /blocks, etc.) se mueven a la carpeta /en/blog/ en GitHub para que la asignación de CDN sea lo más sencilla posible.
Con un simple ajuste de la referencia a scripts.js y styles.css en head.html (véase más arriba) es posible indicar que todos los archivos necesarios se cargan desde el directorio base de código respectivo. Para evitar la reescritura de URL, la estructura de carpetas también se crea en el origen de contenido (p. ej. sharepoint o google drive) al tener una estructura de directorio de /en/blog/.
En muchos casos, a medida que la huella de AEM crece en un sitio, hay un momento en el que el código vuelve a moverse a la carpeta raíz y las referencias head.html se ajustan en consecuencia.
Scripts y estilos
Por convención en un proyecto de AEM, head.html hace referencia a styles.css, scripts.js y aem.js ubicados en /scripts y /styles, como puntos de entrada para el código del proyecto.
scripts.js es el lugar donde se encuentra el código javascript personalizado global y donde se activa el código de carga de bloques. styles.css aloja la información de estilo global del sitio y contiene mínimamente la información de diseño global necesaria para mostrar el Pintado de contenido más grande (LCP).
Como los tres archivos se cargan antes de que se pueda mostrar la página, es importante que se mantengan relativamente pequeños y se ejecuten de forma eficaz.
Más allá de styles.css, se utiliza comúnmente un archivo lazy-styles.css, que se carga después del evento LCP y, por lo tanto, puede contener información CSS más lenta o más lenta. Este podría ser un buen lugar para fuentes o CSS global que esté debajo del pliegue.
Además de scripts.js, está delayed.js, que se usa con más frecuencia. Esto es una red global para bibliotecas que deben cargarse en una página, pero que deben evitar que interfieran con la entrega de la página. Este es un buen lugar para el código que está fuera del control del proyecto y que generalmente incluye la pila de martech y otras bibliotecas.
Consulte el documento Mantener el rendimiento web 100 para obtener más información sobre cómo optimizar el rendimiento del sitio.
Bloques
La mayoría del código CSS y JavaScript específico del proyecto se almacena en bloques. Los autores crean bloques en sus documentos. A continuación, los desarrolladores escriben el código correspondiente que aplica estilo a los bloques con CSS o decora el DOM para tomar el marcado de un bloque y transformarlo a la estructura que sea necesaria o conveniente para el estilo y la funcionalidad deseados.
El nombre del bloque se usa como nombre de carpeta de un bloque, así como el nombre de archivo de los archivos .css y .js que carga el cargador de bloques cuando se usa un bloque en una página.
El nombre del bloque también se utiliza como nombre de clase CSS en el bloque para permitir un estilo intuitivo. El javascript se carga como un módulo (ESM) y exporta una función predeterminada que se ejecuta como parte de la carga del bloque.
Un ejemplo sencillo es el Bloque de columnas. Añade clases adicionales en JavaScript en función de cuántas columnas haya en la instancia respectiva creada por el autor. Esto le permite utilizar un estilo flexible de contenido que se divide en dos columnas en lugar de tres.
Iconos
La mayoría de los proyectos tienen archivos SVG que normalmente se agregan a la carpeta /icons y los autores pueden hacer referencia a ellos con una notación :<iconname>:. De forma predeterminada, los iconos se insertan en el DOM para que se puedan diseñar con CSS, sin tener que crear símbolos de SVG.