As experiências digitais dependem muito do processamento no cliente, conduzido por códigos complexos de JavaScript e CSS. AEM bibliotecas do lado do cliente (clientlibs) permitem organizar e armazenar centralmente essas bibliotecas do lado do cliente no repositório. Em conjunto com o processo de compilação front-end no arquétipo do AEM Project, o gerenciamento do código front-end para o seu projeto AEM se torna simples.
As vantagens de usar clientlibs em AEM incluem:
Clientlibs são a solução integrada para fornecer CSS e Javascript da AEM.
Os desenvolvedores front-end que estão criando CSS e Javascript para projetos AEM também devem se familiarizar com o AEM Project Archetype e seu processo de compilação front-end automatizado.
Os sites exigem JavaScript e CSS, bem como recursos estáticos, como ícones e fontes da Web, para serem processados no cliente. Uma clientlib é AEM mecanismo de referência (por categoria, se necessário) e que serve tais recursos.
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 HTML. Isso maximiza a eficiência do delivery e permite que esses recursos sejam mantidos centralmente no repositório por proxy, mantendo o acesso protegido.
Todos os ativos JavaScript, CSS e outros ativos front-end devem ser mantidos no módulo ui.front-end do AEM Project Archetype. A flexibilidade do arquétipo permite usar as ferramentas da Web modernas de sua escolha para criar e gerenciar esses recursos.
O arquétipo pode então compilar os recursos em um único arquivo CSS e JS, incorporando-os automaticamente em um cq:clientLibraryFolder
no repositório.
Uma pasta de biblioteca do lado do cliente é um nó de repositório do tipo cq:ClientLibraryFolder
. Sua definição na notação CND é
[cq:ClientLibraryFolder] > sling:Folder
- dependencies (string) multiple
- categories (string) multiple
- embed (string) multiple
- channels (string) multiple
cq:ClientLibraryFolder
os nós podem ser colocados em qualquer lugar dentro da /apps
subárvore do repositório.categories
do nó para identificar as categorias de biblioteca às quais ele pertence.Cada cq:ClientLibraryFolder
é preenchido com um conjunto de arquivos JS e/ou CSS, juntamente com alguns arquivos de suporte (veja abaixo). As propriedades importantes de cq:ClientLibraryFolder
são configuradas da seguinte maneira:
allowProxy
: Como todas as clientlibs devem ser armazenadas em apps
, essa propriedade permite o acesso às bibliotecas de clientes por meio do servlet proxy. Consulte Localizando uma pasta de biblioteca de cliente e Usando o Servlet de bibliotecas de cliente proxy abaixo.categories
: Identifica as categorias nas quais o conjunto de arquivos JS e/ou CSS nesse cq:ClientLibraryFolder
outono. A propriedade categories
, que tem vários valores, permite que uma pasta de biblioteca faça parte de mais de uma categoria (veja abaixo como isso pode ser útil).Se a pasta da biblioteca do cliente contiver um ou mais arquivos de origem que, em 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 extensão .js
ou .css
do nome do arquivo. Por exemplo, o nó de biblioteca chamado cq.jquery
resulta no arquivo gerado chamado cq.jquery.js
ou cq.jquery.css
.
As pastas da biblioteca do cliente contêm os seguintes itens:
js.txt
e/ou um arquivo css.txt
que identifica os arquivos de origem a serem mesclados nos arquivos JS e/ou CSS geradosAs bibliotecas do cliente devem estar localizadas em /apps
. Isso é feito para isolar melhor o código do conteúdo e da configuração.
Para que as bibliotecas do cliente em /apps
sejam acessíveis, um servidor proxy é usado. As ACLs ainda são aplicadas na pasta da biblioteca do cliente, mas o servlet permite que o conteúdo seja lido por /etc.clientlibs/
se a propriedade allowProxy
estiver definida como true
.
https://<host>:<port>/crx/de
)./apps
e clique em Criar > Criar nó.cq:ClientLibraryFolder
. Clique em OK e, em seguida, clique em Salvar tudo.cq:ClientLibraryFolder
, adicione a seguinte propriedade e clique em Salvar tudo:
categories
/etc.clientlibs
, selecione o nó cq:ClientLibraryFolder
, adicione a seguinte propriedade e clique em Salvar tudo:
allowProxy
true
resources
abaixo da pasta da biblioteca do cliente.
resources
, eles não poderão ser referenciados em uma instância de publicação.js.txt
: Use esse nome de arquivo para gerar um arquivo JavaScript.css.txt
: Use esse nome de arquivo para gerar uma folha de estilos em cascata.#base=*[root]*
[root]
pelo caminho para a pasta que contém os arquivos de origem, em relação ao arquivo TXT. Por exemplo, use o seguinte texto quando os arquivos de origem estiverem na mesma pasta que o arquivo TXT:
#base=.
cq:ClientLibraryFolder
:
#base=mobile
#base=[root]
, digite os caminhos dos arquivos de origem relativos à raiz. Coloque cada nome de arquivo em uma linha separada.Quando a pasta da biblioteca do cliente estiver configurada conforme necessário, os seus clientlibs poderão ser solicitados via proxy. Como exemplo:
/apps/myproject/clientlibs/foo
/apps/myprojects/clientlibs/foo/resources/icon.png
A propriedade allowProxy
permite solicitar:
/etc.clientlibs/myprojects/clientlibs/foo.js
/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png
Depois que seus clientlibs forem armazenados e gerenciados com êxito na pasta da biblioteca do cliente, eles poderão ser acessados via HTL.
As bibliotecas do cliente são carregadas por meio de um modelo auxiliar fornecido pela AEM, que pode ser acessado por meio de data-sly-use
. Os modelos de ajuda estão disponíveis neste 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 string ou uma string contendo uma lista de valores separados por vírgula.
Consulte a documentação HTL para obter mais detalhes sobre como carregar clientlibs via HTL.
A maioria dos clientlibs será necessária na instância de publicação AEM. Ou seja, a maioria dos propósitos dos clientlibs é produzir a experiência do usuário final do conteúdo. Para clientlibs em instâncias de publicação, ferramentas de compilação front-end podem ser usadas e implantadas por meio de pastas de biblioteca de cliente, conforme descrito acima.
No entanto, algumas vezes, as bibliotecas do cliente 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 para a instância de criação AEM.
Se precisar usar as bibliotecas do cliente no autor, você poderá criar suas bibliotecas do cliente em /apps
usando os mesmos métodos de publicação, mas escreva-os 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 cliente a uma categoria predefinida da biblioteca de cliente.
AEM fornece várias ferramentas para depurar e testar pastas da biblioteca do cliente.
O componente /libs/cq/granite/components/dumplibs/dumplibs
gera uma página de informações sobre todas as pastas da biblioteca do cliente no sistema. O nó /libs/granite/ui/content/dumplibs
tem 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) e 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.
O componente dumplibs
inclui um seletor de teste que exibe o código-fonte gerado para as tags ui:includeClientLib
. A página inclui código para diferentes combinações de atributos js, css e temáticos.
dumplibs.html
, clique no link no texto Clique aqui para obter o teste de saída.http://<host>:<port>/libs/granite/ui/content/dumplibs.html
categories
da biblioteca do cliente e clique em Enviar Query.Há vários outros recursos que são suportados pelas pastas da biblioteca do cliente no AEM. No entanto, estes não são necessários para AEM como Cloud Service e, como tal, a sua utilização é desencorajada. Eles estão listados aqui para estarem completos.
Esses recursos adicionais das Pastas de biblioteca do cliente não são necessários em AEM como Cloud Service e, como tal, seu uso é desencorajado. Eles estão listados aqui para estarem completos.
As configurações adicionais da biblioteca do cliente podem ser controladas pelo painel Adobe Granite HTML Library Manager do Console do Sistema em https://<host>:<port>/system/console/configMgr
).
As propriedades adicionais da pasta incluem permitir o controle de dependências e incorporações, mas geralmente não são mais necessárias e seu uso é desencorajado:
dependencies
: Esta é uma lista de outras categorias da biblioteca do cliente das quais esta pasta da biblioteca depende. Por exemplo, dados dois nós cq:ClientLibraryFolder
F
e G
, se um arquivo em F
exigir outro arquivo em G
para funcionar corretamente, pelo menos um dos categories
de G
deve estar entre dependencies
de F
.embed
: Usado para incorporar código de outras bibliotecas. Se o nó F
incorporar nós G
e H
, o HTML resultante será uma concatenação de conteúdo dos nós G
e H
.Quando o código na pasta da biblioteca do cliente fizer referência a outras bibliotecas, identifique as outras bibliotecas como dependências. A tag ui:includeClientLib
que faz referência à pasta da biblioteca do cliente faz com que o código HTML inclua um link para o arquivo da biblioteca gerado, bem como as dependências.
As dependências devem ser outras cq:ClientLibraryFolder
. Para identificar dependências, adicione uma propriedade ao nó cq:ClientLibraryFolder
com os seguintes atributos:
Por exemplo, /etc/clientlibs/myclientlibs/publicmain
tem uma dependência na biblioteca cq.jquery
. A página que faz referência à biblioteca principal do cliente gera 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">
Você pode incorporar código de uma biblioteca de cliente em outra biblioteca de 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 que são armazenadas em áreas protegidas do repositório.
É uma prática recomendada manter todos os arquivos relacionados ao aplicativo em sua pasta de aplicativos abaixo de /app
. Também é uma prática recomendada negar o acesso de visitantes do site à pasta /app
. Para satisfazer ambas as práticas recomendadas, crie uma pasta de biblioteca de cliente abaixo da pasta /etc
que incorpora a biblioteca de cliente que está abaixo de /app
.
Use a propriedade categoria para identificar a pasta da biblioteca do cliente a ser incorporada. Para incorporar a biblioteca, adicione uma propriedade ao nó de incorporação cq:ClientLibraryFolder
, usando os seguintes atributos de propriedade:
cq:ClientLibraryFolder
nó a ser incorporado.Em alguns casos, você pode descobrir que o HTML final gerado para a página típica pela sua instância de publicação inclui um número relativamente grande de elementos <script>
.
Nesses casos, pode ser útil combinar todo o código da biblioteca do cliente necessário em um único arquivo para que o número de solicitações de ida e volta no carregamento da página seja reduzido. Para fazer isso, você pode embed
as bibliotecas necessárias na biblioteca de cliente específica do aplicativo usando a propriedade embed do nó cq:ClientLibraryFolder
.
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 ao público /etc/client/libraries/myclientlibs/publicmain
incorpora a biblioteca /apps/myapp/clientlib
do cliente:
O arquivo main.css
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 gerado pelo nó publicmain
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%;
}
Para rastrear a origem do código incorporado ou garantir que as bibliotecas de clientes incorporadas produzam 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 parâmetro debugClientLibs=true
ao URL da sua página da Web. A biblioteca gerada contém @import
instruções em vez do código incorporado.
No exemplo na seção anterior Incorporando código de outras bibliotecas, a pasta da biblioteca de cliente /etc/client/libraries/myclientlibs/publicmain
incorpora a pasta da biblioteca de cliente /apps/myapp/clientlib
. 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">
A abertura do arquivo publicmain.css
revela o seguinte código:
@import url("/apps/myapp/clientlib/styles/main.css");
?debugClientLibs=true
AEM permite pré-processadores e entregas conectáveis com suporte para YUI Compressor para CSS e JavaScript e Google Closure Compiler (GCC) para JavaScript com YUI definido como AEM pré-processador padrão.
Os pré-processadores conectáveis permitem uma utilização flexível, incluindo:
Por padrão, AEM usa o Compressor YUI. Consulte a documentação do YUI Compressor GitHub para obter uma lista de problemas conhecidos. Mudar para o compressor GCC para clientlibs específicos pode resolver alguns problemas observados ao utilizar IU.
Não coloque uma biblioteca minimizada em uma biblioteca cliente. Em vez disso, forneça a biblioteca bruta e, se for necessário a miniificação, use as opções dos pré-processadores.
Você pode optar por configurar a configuração dos pré-processadores por biblioteca do cliente ou por todo o sistema.
cssProcessor
e jsProcessor
no nó clientlibraryUma configuração de pré-processador no nó clientlib tem prioridade sobre a configuração OSGI.
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
jsProcessor: [
"default:typescript",
"min:typescript",
"min:gcc;obfuscate=true"
]
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 a documentação da GCC.
A IU é definida como a miniatura padrão no AEM. Para alterar para GCC, siga estas etapas.
http://<host>:<portY/system/console/configMgr
)min:gcc
.
min:gcc;obfuscate=true
.