Uso de bibliotecas do lado do cliente no AEM as a Cloud Service using-client-side-libraries

As experiências digitais dependem muito do processamento do lado do cliente orientado por códigos JavaScript e CSS complexos. Bibliotecas do lado do cliente do AEM (clientlibs) permitem organizar e armazenar centralmente essas bibliotecas do lado do cliente no repositório. Juntamente com a processo de build de front-end no arquétipo de projeto AEM, gerenciar o código de front-end do projeto AEM se torna simples.

As vantagens de usar clientlibs no AEM incluem:

As clientlibs são a solução integrada para fornecer CSS e JavaScript do AEM.

O que são bibliotecas do lado do cliente what-are-clientlibs

Os sites exigem JavaScript e CSS, e recursos estáticos, como ícones e fontes da Web, para serem processados no lado do cliente. Uma clientlib é um mecanismo AEM para fazer referência (por categoria, se necessário) e servir esses recursos.

O AEM coleta o CSS e o JavaScript do site em um único arquivo, em um local central, para garantir que apenas uma cópia de qualquer recurso seja incluída na saída do HTML. Isso maximiza a eficiência da entrega e permite que esses recursos sejam mantidos centralmente no repositório via proxy, mantendo o acesso seguro.

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

Todos os ativos JavaScript, CSS e outros ativos de front-end devem ser mantidos no Módulo ui.frontend do Arquétipo de projeto AEM. A flexibilidade do arquétipo permite usar suas ferramentas da Web modernas preferidas para criar e gerenciar esses recursos.

O arquétipo pode então compilar os recursos em arquivos CSS e JS únicos, incorporando-os automaticamente em um cq:clientLibraryFolder no repositório.

Estrutura da pasta da biblioteca do lado do cliente clientlib-folders

Uma pasta de biblioteca do lado do cliente é um nó de repositório do tipo cq:ClientLibraryFolder. A sua definição no Notação CND é

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

Each cq:ClientLibraryFolder O é preenchido com um conjunto de arquivos JS e/ou CSS, juntamente com alguns arquivos de suporte (veja abaixo). Propriedades importantes do cq:ClientLibraryFolder são configurados da seguinte maneira:

Se a pasta da biblioteca do cliente contiver um ou mais arquivos de código-fonte que, no tempo de execução, serão mesclados em um único arquivo JS e/ou CSS. O nome do arquivo gerado é o nome do nó com a variável .js ou .css extensão do nome do arquivo. Por exemplo, o nó de biblioteca chamado cq.jquery resultados no arquivo gerado chamado cq.jquery.js ou cq.jquery.css.

As pastas da biblioteca do cliente contêm os seguintes itens:

Criação de pastas de bibliotecas do lado do cliente creating-clientlib-folders

As bibliotecas de clientes devem estar localizadas em /apps. Essa regra é necessária para isolar melhor o código do conteúdo e da configuração.

Para que as bibliotecas de clientes em /apps para ser acessível, um servlet proxy é usado. As ACLs ainda são aplicadas na pasta da biblioteca do cliente, mas o servlet permite que o conteúdo seja lido via /etc.clientlibs/ se a variável allowProxy propriedade está definida como true.

Disponibilização de bibliotecas do lado do cliente serving-clientlibs

Assim que a pasta da biblioteca do cliente for configurado conforme necessário, suas clientlibs podem ser solicitadas por proxy. Como exemplo:

A variável allowProxy permite solicitar:

Carregamento de bibliotecas de clientes via HTL loading-via-htl

Depois que as clientlibs forem armazenadas e gerenciadas com êxito na pasta da biblioteca do cliente, elas poderão ser acessadas por HTL.

As bibliotecas de clientes são carregadas por meio de um modelo auxiliar fornecido pelo AEM, que pode ser acessado por meio de data-sly-use. Os modelos auxiliares estão disponíveis nesse arquivo, que pode ser chamado por meio de data-sly-call.

Cada modelo auxiliar espera uma opção categories para fazer referência às bibliotecas de clientes desejadas. Essa opção pode ser uma matriz de valores de cadeias de caracteres ou uma cadeia contendo uma lista de valores separados por vírgula.

Consulte a documentação do HTL para obter mais detalhes sobre como carregar clientlibs por HTL.

Bibliotecas de clientes no Autor versus Publicar clientlibs-author-publish

A maioria das clientlibs é necessária na instância de publicação do AEM. Ou seja, a finalidade da maioria das clientlibs é produzir a experiência do usuário final do conteúdo. Para clientlibs em instâncias de publicação, ferramentas de build de front-end pode ser usado e implantado via pastas da biblioteca do cliente conforme descrito acima.

No entanto, há momentos em que as bibliotecas de clientes podem ser necessárias para personalizar a experiência de criação. Por exemplo, personalizar uma caixa de diálogo pode exigir a implantação de pequenos bits de CSS ou JS na instância de criação do AEM.

Gerenciamento de bibliotecas de clientes no Author clientlibs-on-author

Se precisar usar bibliotecas de clientes no autor, você poderá criar suas bibliotecas de clientes em /apps usando os mesmos métodos de publicação, mas escreva-o diretamente em /apps/.../clientlibs/foo em vez de criar um projeto inteiro para gerenciá-lo.

Em seguida, você pode "conectar" ao JS de criação adicionando suas bibliotecas de clientes a uma categoria de biblioteca de clientes pronta para uso.

Ferramentas de depuração debugging-tools

O AEM fornece várias ferramentas para depurar e testar pastas da biblioteca do cliente.

Descubra bibliotecas de clientes discover-client-libraries

A variável /libs/cq/granite/components/dumplibs/dumplibs O componente gera uma página de informações sobre todas as pastas da biblioteca do cliente no sistema. A variável /libs/granite/ui/content/dumplibs possui o componente como um tipo de recurso. Para abrir a página, use o seguinte URL (alterando o host e a porta conforme necessário):

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

As informações incluem o caminho e o tipo da biblioteca (CSS ou JS), bem como os valores dos atributos da biblioteca, como categorias e dependências. As tabelas subsequentes na página mostram as bibliotecas em cada categoria e canal.

Consulte Saída gerada see-generated-output

A variável dumplibs componente inclui um seletor de teste que exibe o código-fonte gerado para ui:includeClientLib específicos. A página inclui código para diferentes combinações de js, css e atributos temáticos.

Recursos adicionais da pasta da biblioteca do cliente additional-features

Há vários outros recursos compatíveis com as pastas da biblioteca do cliente no AEM. No entanto, estes não são necessários para o AEM as a Cloud Service e, como tal, seu uso é desencorajado. Eles estão listados aqui para fins de integridade.

Adobe Granite HTML LIbrary Manager html-library-manager

As configurações adicionais da biblioteca do cliente podem ser controladas por meio da Gerenciador de biblioteca de HTML do Adobe Granite painel do Console do sistema em https://<host>:<port>/system/console/configMgr).

Propriedades adicionais da pasta additional-folder-properties

As propriedades adicionais da pasta incluem permitir controle de dependências e incorporações, mas geralmente não são mais necessárias e seu uso não é incentivado:

Vinculação a Dependências linking-to-dependencies

Quando o código na pasta da biblioteca do cliente fizer referência a outras bibliotecas, identifique as outras bibliotecas como dependências. A variável ui:includeClientLib a tag que faz referência à pasta da biblioteca do cliente faz com que o código HTML inclua um link para o arquivo de biblioteca gerado e as dependências.

As dependências devem ser outras cq:ClientLibraryFolder. Para identificar dependências, adicione uma propriedade à cq:ClientLibraryFolder com os seguintes atributos:

Por exemplo, a variável /etc/clientlibs/myclientlibs/publicmain tem uma dependência no cq.jquery biblioteca. A página que faz referência à biblioteca cliente principal gera um HTML que inclui o seguinte código:

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

Como incorporar código de outras bibliotecas embedding-code-from-other-libraries

Você pode incorporar o código de uma biblioteca do cliente a outra biblioteca do cliente. No tempo de execução, os arquivos JS e CSS gerados da biblioteca de incorporação incluem o código da biblioteca incorporada.

A incorporação do código é útil para fornecer acesso às bibliotecas armazenadas em áreas seguras do repositório.

Pastas de bibliotecas de clientes específicas do aplicativo app-specific-client-library-folders

É uma prática recomendada manter todos os arquivos relacionados ao aplicativo na pasta do aplicativo abaixo /apps. Também é uma prática recomendada negar acesso aos visitantes do site à /apps pasta. Para atender a ambas as práticas recomendadas, crie uma pasta de biblioteca do cliente abaixo de /etc pasta que incorpora a biblioteca do cliente abaixo /apps.

Use a propriedade categories para identificar a pasta da biblioteca do cliente a ser incorporada. Para incorporar a biblioteca, adicione uma propriedade à incorporação cq:ClientLibraryFolder usando os seguintes atributos de propriedade:

Utilização de incorporação para minimizar solicitações using-embedding-to-minimize-requests

Em alguns casos, você pode descobrir que o HTML final gerado para a página típica pela instância de publicação inclui um número relativamente grande de <script> elementos.

Nesses casos, pode ser útil combinar todo o código da biblioteca do cliente necessário no em um único arquivo para reduzir o número de solicitações de ida e volta no carregamento da página. Para fazer isso, você pode embed as bibliotecas necessárias na biblioteca do cliente específica do aplicativo usando a propriedade embed do cq:ClientLibraryFolder nó.

Caminhos em arquivos CSS paths-in-css-files

Quando você incorpora arquivos CSS, o código CSS gerado usa caminhos para recursos relativos à biblioteca de incorporação. Por exemplo, a biblioteca acessível publicamente /etc/client/libraries/myclientlibs/publicmain incorpora o /apps/myapp/clientlib biblioteca do cliente:

A variável main.css O arquivo contém o seguinte estilo:

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

O arquivo CSS que o publicmain O nó gerado contém o seguinte estilo, usando o URL da imagem original:

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

Consulte Arquivos incorporados na saída do HTML see-embedded-files

Para rastrear a origem do código incorporado ou garantir que as bibliotecas de clientes incorporadas estejam produzindo os resultados esperados, você pode ver os nomes dos arquivos que estão sendo incorporados no tempo de execução. Para ver os nomes dos arquivos, anexe o debugClientLibs=true para o URL da sua página da Web. A biblioteca gerada contém @import instruções em vez do código incorporado.

No exemplo no anterior Como incorporar código de outras bibliotecas seção, a variável /etc/client/libraries/myclientlibs/publicmain a pasta da biblioteca do cliente incorpora o /apps/myapp/clientlib pasta da biblioteca do cliente. Anexar o parâmetro à página da Web produz o seguinte link no código-fonte da página da Web:

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

Abrir o publicmain.css revela o seguinte código:

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

Uso de pré-processadores using-preprocessors

O AEM permite pré-processadores conectáveis e é fornecido com suporte para Compactador YUI para CSS e JavaScript e Compilador de Fechamento do Google (GCC) para JavaScript com YUI definido como pré-processador padrão do AEM.

Os pré-processadores conectáveis permitem um uso flexível, incluindo:

Uso usage

Você pode optar por definir a configuração de pré-processadores por biblioteca do cliente ou em todo o sistema.

Uma configuração de pré-processador no nó clientlib tem prioridade sobre a configuração OSGI.

Formato e exemplos format-and-examples

Formato format

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

Compactador YUI para Minificação CSS e GCC para JS yui-compressor-for-css-minification-and-gcc-for-js

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

Digitar script para pré-processar e, em seguida, GCC para minificar e ofuscar typescript-to-preprocess-and-then-gcc-to-minify-and-obfuscate

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

Opções adicionais 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 obter mais detalhes sobre as opções de GCC, consulte Documentação do GCC.

Definir Minificador Padrão do Sistema set-system-default-minifier

A interface do usuário é definida como o minificador padrão no AEM. Para alterar isso para GCC, siga estas etapas.