Uso de bibliotecas del lado del cliente en AEM as a Cloud Service using-client-side-libraries

Las experiencias digitales dependen en gran medida del procesamiento del lado del cliente impulsado por código CSS y JavaScript complejo. AEM Las bibliotecas del lado del cliente (clientlibs) le permiten organizar y almacenar de forma centralizada estas bibliotecas del lado del cliente dentro del repositorio. AEM AEM Junto con el proceso de compilación del front-end en el tipo de archivo del proyecto de, la administración del código del front-end para el proyecto de la se vuelve sencilla.

AEM Entre las ventajas de usar clientlibs en la práctica se incluyen las siguientes:

Clientlibs es la solución integrada para ofrecer CSS y JavaScript AEM desde el punto de vista de los clientes

Qué son las bibliotecas del lado del cliente what-are-clientlibs

Los sitios requieren JavaScript y CSS, y recursos estáticos como iconos y fuentes web para procesarlos en el lado del cliente. AEM Una clientlib es el mecanismo de referencia que se utiliza para hacer referencia a (por categoría si es necesario) y para servir dichos recursos.

AEM el CSS y el JavaScript del sitio en un solo archivo, en una ubicación central, para garantizar que solo se incluya una copia de cualquier recurso en la salida del HTML. Esto maximiza la eficacia de la entrega y permite que estos recursos se mantengan centralmente en el repositorio a través de proxy, manteniendo el acceso seguro.

Desarrollo front-end para AEM as a Cloud Service fed-for-aemaacs

Todos los recursos de JavaScript AEM, CSS y otros recursos front-end deben mantenerse en el módulo ui.frontend del tipo de archivo del proyecto de. La flexibilidad del tipo de archivo le permite utilizar las herramientas web modernas que elija para crear y administrar estos recursos.

A continuación, el tipo de archivo puede compilar los recursos en archivos CSS y JS únicos, incrustándolos automáticamente en un cq:clientLibraryFolder del repositorio.

Estructura de carpetas de biblioteca del lado del cliente clientlib-folders

Una carpeta de biblioteca del lado del cliente es un nodo de repositorio de tipo cq:ClientLibraryFolder. Su definición en notación CND es

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple

Cada cq:ClientLibraryFolder se rellena con un conjunto de archivos JS o CSS, junto con algunos archivos auxiliares (ver a continuación). Las propiedades importantes de cq:ClientLibraryFolder se configuran de la siguiente manera:

Si la carpeta de la biblioteca cliente contiene uno o varios archivos de código fuente que, en tiempo de ejecución, se combinan en un solo archivo JS o CSS. El nombre del archivo generado es el nombre del nodo con la extensión de nombre de archivo .js o .css. Por ejemplo, el nodo de biblioteca denominado cq.jquery genera el archivo generado denominado cq.jquery.js o cq.jquery.css.

Las carpetas de la biblioteca de cliente contienen los siguientes elementos:

Creación de carpetas de biblioteca del lado del cliente creating-clientlib-folders

Las bibliotecas de cliente deben encontrarse en /apps. Esta regla es necesaria para aislar mejor el código del contenido y la configuración.

Para que se pueda acceder a las bibliotecas de cliente de /apps, se utiliza un servlet proxy. Las ACL siguen aplicándose en la carpeta de biblioteca del cliente, pero el servlet permite que el contenido se lea a través de /etc.clientlibs/ si la propiedad allowProxy está establecida en true.

Servicio de bibliotecas del lado del cliente serving-clientlibs

Una vez que la carpeta de la biblioteca de cliente esté configurada según se requiera, sus clientlibs se podrán solicitar mediante proxy. A modo de ejemplo:

La propiedad allowProxy le permite solicitar:

Carga de bibliotecas de cliente mediante HTL loading-via-htl

Una vez que los clientlibs se hayan almacenado y administrado correctamente en la carpeta de biblioteca de cliente, se puede acceder a ellos a través de HTL.

AEM Las bibliotecas de cliente se cargan a través de una plantilla de ayuda proporcionada por, a la cual se puede tener acceso mediante data-sly-use. Las plantillas de ayuda están disponibles en este archivo, al que se puede llamar mediante data-sly-call.

Cada plantilla de ayuda espera una opción categories para hacer referencia a las bibliotecas de cliente deseadas. Esa opción puede ser una matriz de valores de cadena o una cadena que contenga una lista de valores separados por comas.

Consulte la documentación de HTL para obtener más información sobre cómo cargar clientlibs a través de HTL.

Bibliotecas de cliente en Author y Publish clientlibs-author-publish

AEM La mayoría de los clientlibs son obligatorios en la instancia de publicación de la. Es decir, la mayoría de los propósitos de los clientlibs son producir la experiencia del usuario final del contenido. Para clientlibs en instancias de publicación, herramientas de compilación del front-end se pueden usar e implementar a través de carpetas de biblioteca de cliente como se describe más arriba.

Sin embargo, hay ocasiones en que puede ser necesario usar bibliotecas de cliente para personalizar la experiencia de creación. AEM Por ejemplo, la personalización de un cuadro de diálogo puede requerir la implementación de pequeños bits de CSS o JS en la instancia de creación de la aplicación de la instancia de creación de la.

Administración de bibliotecas de cliente en Author clientlibs-on-author

Si necesita usar bibliotecas de cliente en Author, puede crear sus bibliotecas de cliente en /apps utilizando los mismos métodos que para Publish, pero escríbalo directamente en /apps/.../clientlibs/foo en lugar de crear un proyecto completo para administrarlo.

A continuación, puede "conectar" al JS de creación añadiendo las bibliotecas de cliente a una categoría de biblioteca de cliente predeterminada.

Herramientas de depuración debugging-tools

AEM proporciona varias herramientas para depurar y probar carpetas de la biblioteca de cliente.

Descubrir bibliotecas de cliente discover-client-libraries

El componente /libs/cq/granite/components/dumplibs/dumplibs genera una página de información sobre todas las carpetas de la biblioteca de cliente del sistema. El nodo /libs/granite/ui/content/dumplibs tiene el componente como tipo de recurso. Para abrir la página, utilice la siguiente URL (cambiando el host y el puerto según sea necesario):

https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html

La información incluye la ruta y el tipo de la biblioteca (CSS o JS) y los valores de los atributos de la biblioteca, como las categorías y dependencias. Las tablas posteriores de la página muestran las bibliotecas de cada categoría y canal.

Consulte Salida generada see-generated-output

El componente dumplibs incluye un selector de prueba que muestra el código fuente generado para las etiquetas ui:includeClientLib. La página incluye código para diferentes combinaciones de atributos js, css y temáticos.

Funciones adicionales de carpeta de biblioteca de cliente additional-features

AEM Hay otras funciones compatibles con las carpetas de biblioteca de cliente en la documentación de la biblioteca de. Sin embargo, no son necesarios en AEM as a Cloud Service y, por lo tanto, se desaconseja su uso. Se enumeran aquí para completar la información.

Adobe Granite HTML LIbrary Manager html-library-manager

Se puede controlar la configuración adicional de la biblioteca de cliente a través del panel Administrador de bibliotecas de Adobe Granite HTML de la consola del sistema en https://<host>:<port>/system/console/configMgr).

Propiedades de carpeta adicionales additional-folder-properties

Las propiedades de carpeta adicionales incluyen permitir el control de dependencias e incrustaciones, pero generalmente ya no son necesarias y se desaconseja su uso:

Vinculación a dependencias linking-to-dependencies

Cuando el código de la carpeta de la biblioteca de cliente haga referencia a otras bibliotecas, identifique las demás bibliotecas como dependencias. La etiqueta ui:includeClientLib que hace referencia a la carpeta de biblioteca de cliente hace que el código del HTML incluya un vínculo al archivo de biblioteca generado y a las dependencias.

Las dependencias deben ser otras cq:ClientLibraryFolder. Para identificar dependencias, agregue una propiedad al nodo cq:ClientLibraryFolder con los atributos siguientes:

Por ejemplo, /etc/clientlibs/myclientlibs/publicmain depende de la biblioteca cq.jquery. La página que hace referencia a la biblioteca de cliente principal genera un HTML que incluye el siguiente código:

<script src="/etc/clientlibs/foundation/cq.jquery.js" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js" type="text/javascript">

Incrustar Código De Otras Bibliotecas embedding-code-from-other-libraries

Puede incrustar código de una biblioteca de cliente en otra biblioteca de cliente. En tiempo de ejecución, los archivos JS y CSS generados de la biblioteca de incrustación incluyen el código de la biblioteca incrustada.

La incrustación de código resulta útil para proporcionar acceso a bibliotecas almacenadas en áreas seguras del repositorio.

Carpetas de la biblioteca de clientes específicas de la aplicación app-specific-client-library-folders

Se recomienda mantener todos los archivos relacionados con la aplicación en la carpeta de su aplicación por debajo de /apps. También se recomienda denegar el acceso a los visitantes del sitio web a la carpeta /apps. Para satisfacer ambas prácticas recomendadas, cree una carpeta de biblioteca de cliente debajo de la carpeta /etc que incruste la biblioteca de cliente debajo de /apps.

Utilice la propiedad categories para identificar la carpeta de biblioteca de cliente que se va a incrustar. Para incrustar la biblioteca, agregue una propiedad al nodo cq:ClientLibraryFolder que se está incrustando, utilizando los siguientes atributos de propiedad:

Uso de la incrustación para minimizar las solicitudes using-embedding-to-minimize-requests

En algunos casos, es posible que el HTML final que genera la instancia de publicación para la página típica incluya un número relativamente grande de <script> elementos.

En estos casos, puede resultar útil combinar todo el código de biblioteca de cliente necesario en un solo archivo para reducir el número de solicitudes de ida y vuelta al cargar la página. Para ello, puede embed las bibliotecas necesarias en su biblioteca de cliente específica de la aplicación mediante la propiedad embed del nodo cq:ClientLibraryFolder.

Rutas en archivos CSS paths-in-css-files

Al incrustar archivos CSS, el código CSS generado utiliza rutas a recursos relativos a la biblioteca de incrustación. Por ejemplo, la biblioteca de acceso público /etc/client/libraries/myclientlibs/publicmain incrusta la biblioteca de cliente /apps/myapp/clientlib:

El archivo main.css contiene el siguiente estilo:

body {
  padding: 0;
  margin: 0;
  background: url(images/bg-full.jpg) no-repeat center top;
  width: 100%;
}

El archivo CSS que genera el nodo publicmain contiene el siguiente estilo, con la dirección URL de la imagen original:

body {
  padding: 0;
  margin: 0;
  background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
  width: 100%;
}

Consulte Archivos incrustados en la salida del HTML see-embedded-files

Para realizar un seguimiento del origen del código incrustado o para asegurarse de que las bibliotecas de cliente incrustadas producen los resultados esperados, puede ver los nombres de los archivos que se están incrustando durante la ejecución. Para ver los nombres de archivo, agregue el parámetro debugClientLibs=true a la dirección URL de la página web. La biblioteca que se genera contiene @import instrucciones en lugar del código incrustado.

En el ejemplo de la sección Incrustar código de otras bibliotecas anterior, la carpeta de biblioteca de cliente /etc/client/libraries/myclientlibs/publicmain incrusta la carpeta de biblioteca de cliente /apps/myapp/clientlib. Al anexar el parámetro a la página web, se produce el siguiente vínculo en el código fuente de la página web:

<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css">

Al abrir el archivo publicmain.css, se muestra el siguiente código:

@import url("/apps/myapp/clientlib/styles/main.css");

Uso de preprocesadores using-preprocessors

El preprocesador YUI Compressor para CSS y JavaScript y Google Closure Compiler (GCC) para JavaScript con YUI establecido como preprocesador predeterminado para la conexión permite que los preprocesadores se puedan conectar y los envíos con soporte para YUI Compressor para CSS y AEM y AEM Closure Compiler (GCC) para con YUI establecido como preprocesador predeterminado para la conexión.

Los preprocesadores conectables permiten un uso flexible que incluye:

Uso usage

Puede elegir configurar la configuración de preprocesadores por biblioteca de cliente o en todo el sistema.

Una configuración de preprocesador en el nodo clientlib tiene prioridad sobre la configuración OSGI.

Formato y ejemplos format-and-examples

Formato format

config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;

Compresor YUI para minificación de CSS y GCC para JS yui-compressor-for-css-minification-and-gcc-for-js

cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]

Escriba un script para preprocesar y luego GCC para minimizar y proteger typescript-to-preprocess-and-then-gcc-to-minify-and-obfuscate

jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]

Opciones adicionales de GCC additional-gcc-options

failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

Para obtener más información sobre las opciones de GCC, consulte Documentación de GCC.

Establecer minificador predeterminado del sistema set-system-default-minifier

AEM YUI se establece como el minificador predeterminado en la interfaz de usuario de. Para cambiar esto a GCC, siga estos pasos.