Utilizzo di librerie lato client su AEM come Cloud Service

Le esperienze digitali dipendono in larga misura dall'elaborazione sul lato client basata su codice JavaScript e CSS complessi. AEM Client-Side Libraries (clientlibs) consentono di organizzare e archiviare centralmente queste librerie lato client all'interno dell'archivio. Unita al processo di build front-end nell'archetipo AEM progetto, la gestione del codice front-end per il progetto AEM diventa semplice.

I vantaggi dell'uso di clientlibes in AEM includono:

  • Il codice lato client viene memorizzato nell'archivio come tutti gli altri codici e contenuti dell'applicazione
  • Clientlibs in AEM può aggregare tutti i CSS e JS in un unico file
  • Esposizione di clientlibs tramite un percorso accessibile tramite dispatcher
  • Consente la riscrittura dei percorsi per i file o le immagini di riferimento

Clientlibs è la soluzione integrata per la distribuzione di CSS e Javascript da AEM.

SUGGERIMENTO

Gli sviluppatori front-end che creano file CSS e Javascript per AEM progetti devono anche familiarizzare con il AEM Project Archetype e con il suo processo automatizzato di build front-end.

Che cosa sono le librerie lato client

I siti richiedono l'elaborazione di JavaScript e CSS e di risorse statiche come icone e font Web sul lato client. Una clientlib è AEM meccanismo di riferimento (se necessario per categoria) e di gestione di tali risorse.

AEM raccoglie i file CSS e Javascript del sito in un singolo file, in una posizione centrale, per garantire che solo una copia di qualsiasi risorsa sia inclusa nell'output HTML. Questo ottimizza l'efficienza della distribuzione e consente di mantenere le risorse a livello centrale nell'archivio tramite proxy, garantendo la sicurezza dell'accesso.

Sviluppo front-end per AEM come Cloud Service

Tutte le risorse front-end JavaScript, CSS e altre devono essere mantenute nel modulo ui.frontend dell'archivio AEM progetto. La flessibilità di questo archetipo consente di utilizzare i moderni strumenti Web a scelta per creare e gestire queste risorse.

L'archetype può quindi compilare le risorse in singoli file CSS e JS, incorporandoli automaticamente in un cq:clientLibraryFolder nella directory archivio.

Struttura cartella libreria lato client

Una cartella libreria lato client è un nodo di repository di tipo cq:ClientLibraryFolder. La sua definizione in notazione CND è

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple
  • cq:ClientLibraryFolder i nodi possono essere posizionati ovunque all'interno della /apps sottostruttura dell'archivio.
  • Utilizzare la proprietà categories del nodo per identificare le categorie di libreria alle quali appartiene.

Ogni file cq:ClientLibraryFolder viene popolato con un set di file JS e/o CSS, insieme ad alcuni file di supporto (vedere di seguito). Le proprietà importanti di cq:ClientLibraryFolder sono configurate come segue:

  • allowProxy: Poiché tutti i clientlibs devono essere memorizzati in apps, questa proprietà consente l'accesso a clientlibraries tramite servlet proxy. Vedere Individuazione di una cartella della libreria client e Utilizzo del servlet delle librerie client proxy di seguito.
  • categories: Identifica le categorie in cui il set di file JS e/o CSS entro questo cq:ClientLibraryFolder autunno. La proprietà categories, con un valore multiplo, consente a una cartella di libreria di appartenere a più categorie (vedere di seguito per informazioni su come potrebbe essere utile).

Se la cartella della libreria client contiene uno o più file sorgente che, in fase di esecuzione, vengono uniti in un singolo file JS e/o CSS. Il nome del file generato è il nome del nodo con l'estensione del nome di file .js o .css. Ad esempio, il nodo della libreria denominato cq.jquery restituisce il file generato denominato cq.jquery.js o cq.jquery.css.

Le cartelle della libreria client contengono i seguenti elementi:

  • I file sorgente JS e/o CSS
  • Risorse statiche che supportano stili CSS, ad esempio icone, font Web ecc.
  • Un file js.txt e/o un file css.txt che identifica i file sorgente da unire nei file JS e/o CSS generati

Architettura Clientlib

Creazione di cartelle libreria lato client

Le librerie client devono trovarsi in /apps. Ciò consente di isolare meglio il codice dal contenuto e dalla configurazione.

Per rendere accessibili le librerie client in /apps, viene utilizzato un servlet proxy. Gli ACL sono ancora applicati alla cartella della libreria client, ma il servlet consente la lettura del contenuto tramite /etc.clientlibs/ se la proprietà allowProxy è impostata su true.

  1. Aprite il CRXDE Lite in un browser Web (https://<host>:<port>/crx/de).
  2. Selezionare la cartella /apps e fare clic su Crea > Crea nodo.
  3. Immettete un nome per la cartella della libreria e nell'elenco Tipo selezionate cq:ClientLibraryFolder. Fare clic su OK, quindi fare clic su Salva tutto.
  4. Per specificare la categoria o le categorie a cui appartiene la libreria, selezionare il nodo cq:ClientLibraryFolder, aggiungere la seguente proprietà, quindi fare clic su Salva tutto:
    • Nome: categories
    • Tipo: Stringa
    • Valore: Nome categoria
    • Multi: Selezionato
  5. Affinché le librerie client siano accessibili tramite proxy in /etc.clientlibs, selezionare il nodo cq:ClientLibraryFolder, aggiungere la seguente proprietà, quindi fare clic su Salva tutto:
    • Nome: allowProxy
    • Tipo: booleano
    • Valore: true
  6. Per gestire le risorse statiche, create una sottocartella denominata resources sotto la cartella della libreria client.
    • Se archiviate risorse statiche nella cartella resources, non è possibile fare riferimento a tali risorse in un'istanza pubblicata.
  7. Aggiungete i file sorgente alla cartella della libreria.
    • Questo è in genere fatto dal processo di compilazione front-end del AEM Project Archetype.
    • Se necessario, potete organizzare i file sorgente in sottocartelle.
  8. Selezionate la cartella della libreria client e fate clic su Crea > Crea file.
  9. Nella casella Nome file digitare uno dei seguenti nomi di file e fare clic su OK:
    • js.txt: Utilizzate questo nome file per generare un file JavaScript.
    • css.txt: Utilizzate questo nome file per generare un foglio di stile a cascata.
  10. Aprite il file e digitate il testo seguente per identificare la radice del percorso dei file sorgente:
    • #base=*[root]*
    • Sostituire [root] con il percorso della cartella che contiene i file sorgente, relativo al file TXT. Ad esempio, usate il testo seguente quando i file sorgente si trovano nella stessa cartella del file TXT:
      • #base=.
    • Il codice seguente imposta la radice come cartella denominata mobile sotto il nodo cq:ClientLibraryFolder:
      • #base=mobile
  11. Sulle righe sottostanti #base=[root], digitare i percorsi dei file di origine relativi alla radice. Posizionare ciascun nome file su una riga separata.
  12. Fare clic su Salva tutto.

Server delle librerie lato client

Una volta che la cartella della libreria client è configurata come necessario, i client possono essere richiesti tramite proxy. Ad esempio:

  • Hai una clientlib in /apps/myproject/clientlibs/foo
  • L'immagine è statica in /apps/myprojects/clientlibs/foo/resources/icon.png

La proprietà allowProxy consente di richiedere:

  • clientlib tramite j/etc.clientlibs/myprojects/clientlibs/foo.js
  • Immagine statica tramite /etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png

Caricamento delle librerie client tramite HTL

Una volta che i client sono stati memorizzati e gestiti correttamente nella cartella della libreria client, possono accedervi tramite HTL.

Le librerie client vengono caricate tramite un modello helper fornito da AEM, accessibile tramite data-sly-use. I modelli helper sono disponibili in questo file, che può essere chiamato tramite data-sly-call.

Ogni modello di supporto prevede un'opzione categories per fare riferimento alle librerie client desiderate. Tale opzione può essere una matrice di valori stringa o una stringa contenente un elenco di valori separati da virgola.

Per ulteriori informazioni sul caricamento di clientlibs tramite HTL, consultate la documentazione HTL.

Librerie client su Autore e pubblicazione

La maggior parte dei clientlibs sarà necessaria nell’istanza di pubblicazione AEM. In altre parole, lo scopo della maggior parte dei clienti è quello di produrre l'esperienza dell'utente finale del contenuto. Per i client sulle istanze di pubblicazione, strumenti di compilazione front-end possono essere utilizzati e distribuiti tramite cartelle della libreria client come descritto sopra.

Tuttavia, in alcuni casi potrebbe essere necessario personalizzare l’esperienza di authoring con le librerie client. Ad esempio, la personalizzazione di una finestra di dialogo potrebbe richiedere la distribuzione di piccoli bit di CSS o JS nell’istanza di authoring AEM.

Gestione delle librerie client sull'autore

Se è necessario utilizzare le librerie client per l'authoring, è possibile creare le librerie client in /apps utilizzando gli stessi metodi utilizzati per la pubblicazione, ma scriverle direttamente in /apps/.../clientlibs/foo invece di creare un intero progetto per gestirlo.

Potete quindi eseguire il "collegamento" al JS di authoring aggiungendo le librerie client a una categoria di libreria client out-of-the-box.

Strumenti di debug

AEM fornisce diversi strumenti per il debug e il test delle cartelle della libreria client.

Scopri librerie client

Il componente /libs/cq/granite/components/dumplibs/dumplibs genera una pagina di informazioni su tutte le cartelle della libreria client nel sistema. Il nodo /libs/granite/ui/content/dumplibs ha il componente come tipo di risorsa. Per aprire la pagina, usate il seguente URL (modificando l’host e la porta come richiesto):

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

Le informazioni includono il percorso e il tipo della libreria (CSS o JS) e i valori degli attributi della libreria, come categorie e dipendenze. Le tabelle successive della pagina mostrano le librerie in ogni categoria e canale.

Vedere Uscita generata

Il componente dumplibs include un selettore di test che visualizza il codice sorgente generato per i tag ui:includeClientLib. La pagina include il codice per diverse combinazioni di attributi js, css e a tema.

  1. Per aprire la pagina Test Output, utilizzare uno dei metodi seguenti:
    • Dalla pagina dumplibs.html, fare clic sul collegamento nel testo Fare clic qui per il test dell'output.
    • Aprite il seguente URL nel browser Web (utilizzate un host e una porta diversi come richiesto):
      • http://<host>:<port>/libs/granite/ui/content/dumplibs.html
    • La pagina predefinita mostra l'output per i tag senza valore per l'attributo category.
  2. Per visualizzare l'output di una categoria, digitare il valore della proprietà categories della libreria client e fare clic su Invia query.

Funzionalità aggiuntive della cartella libreria client

Esistono diverse altre funzionalità supportate dalle cartelle della libreria client in AEM. Tuttavia, non sono necessari in AEM come Cloud Service e come tale il loro uso è scoraggiato. Sono elencati qui per completezza.

AVVERTENZA

Queste funzioni aggiuntive delle cartelle della libreria client non sono necessarie in AEM come Cloud Service e pertanto il loro utilizzo non è consigliato. Sono elencati qui per completezza.

Adobe Granite HTML LIbrary Manager

È possibile controllare altre impostazioni della libreria client tramite il pannello Adobe Granite HTML Library Manager della console di sistema all'indirizzo https://<host>:<port>/system/console/configMgr.

Proprietà cartella aggiuntive

Ulteriori proprietà delle cartelle includono l'autorizzazione del controllo di dipendenze e incorporamenti, ma in genere non sono più necessarie e il loro utilizzo non è più consigliato:

  • dependencies: Si tratta di un elenco di altre categorie di libreria client da cui dipende la cartella libreria. Ad esempio, a due nodi cq:ClientLibraryFolder F e G, se un file in F richiede un altro file in G per funzionare correttamente, almeno uno dei categories di G deve essere compreso tra dependencies di F.
  • embed: Utilizzato per incorporare il codice da altre librerie. Se il nodo F incorpora i nodi G e H, l'HTML risultante sarà una concatenazione di contenuto dai nodi G e H.

Collegamento a dipendenze

Quando il codice nella cartella della libreria client fa riferimento ad altre librerie, identificate le altre librerie come dipendenze. Il tag ui:includeClientLib che fa riferimento alla cartella della libreria client causa l'inclusione nel codice HTML di un collegamento al file libreria generato e alle dipendenze.

Le dipendenze devono essere un'altra cq:ClientLibraryFolder. Per identificare le dipendenze, aggiungi una proprietà al nodo cq:ClientLibraryFolder con i seguenti attributi:

  • Nome: dipendenze
  • Tipo: Stringa[]
  • Valori: il valore della proprietà category del nodo cq:ClientLibraryFolder da cui dipende la cartella libreria corrente.

Ad esempio, la /etc/clientlibs/myclientlibs/publicmain ha una dipendenza dalla libreria cq.jquery. La pagina che fa riferimento alla libreria client principale genera codice HTML che include il seguente codice:

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

Incorporazione del codice da altre librerie

Potete incorporare il codice da una libreria client a un'altra libreria client. In fase di esecuzione, i file JS e CSS generati dalla libreria di incorporamento includono il codice della libreria incorporata.

L'incorporazione del codice è utile per fornire l'accesso alle librerie memorizzate nelle aree protette dell'archivio.

Cartelle libreria client specifiche per l'app

È consigliabile mantenere tutti i file relativi alle applicazioni nella cartella dell'applicazione al di sotto di /app. È inoltre consigliabile negare l'accesso ai visitatori del sito Web nella cartella /app. Per soddisfare entrambe le procedure ottimali, create una cartella della libreria client sotto la cartella /etc che incorpora la libreria client che si trova sotto /app.

Utilizzare la proprietà category per identificare la cartella della libreria client da incorporare. Per incorporare la libreria, aggiungere una proprietà al nodo cq:ClientLibraryFolder in cui incorporare, utilizzando i seguenti attributi di proprietà:

  • Nome: embed
  • Tipo: Stringa[]
  • Valore: il valore della proprietà category del cq:ClientLibraryFolder nodo da incorporare.

Utilizzo dell'incorporazione per ridurre al minimo le richieste

In alcuni casi, l’HTML finale generato per la pagina tipica dall’istanza di pubblicazione include un numero relativamente elevato di elementi <script>.

In tali casi, può essere utile combinare tutti i codici libreria client richiesti in un singolo file in modo da ridurre il numero di richieste di andata e ritorno al caricamento della pagina. A questo scopo, è possibile embed inserire le librerie necessarie nella libreria client specifica per l'app utilizzando la proprietà embed del nodo cq:ClientLibraryFolder.

Percorsi nei file CSS

Quando incorporate file CSS, il codice CSS generato utilizza percorsi verso risorse relative alla libreria di incorporamento. Ad esempio, la libreria accessibile al pubblico /etc/client/libraries/myclientlibs/publicmain incorpora la libreria client /apps/myapp/clientlib:

Il file main.css contiene lo stile seguente:

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

Il file CSS generato dal nodo publicmain contiene il seguente stile, utilizzando l'URL dell'immagine originale:

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

Vedere File incorporati in Output HTML

Per tracciare l'origine del codice incorporato o per assicurarsi che le librerie client incorporate producano i risultati previsti, è possibile visualizzare i nomi dei file che vengono incorporati in fase di esecuzione. Per visualizzare i nomi dei file, aggiungete il parametro debugClientLibs=true all'URL della pagina Web. La libreria generata contiene istruzioni @import invece del codice incorporato.

Nell'esempio della sezione precedente Incorporamento del codice da altre librerie, la cartella della libreria client /etc/client/libraries/myclientlibs/publicmain incorpora la cartella della libreria client /apps/myapp/clientlib. L'aggiunta del parametro alla pagina Web genera il seguente collegamento nel codice sorgente della pagina Web:

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

Aprendo il file publicmain.css viene visualizzato il seguente codice:

@import url("/apps/myapp/clientlib/styles/main.css");
  1. Nella casella dell’indirizzo del browser Web, aggiungete il testo seguente all’URL del codice HTML:
    • ?debugClientLibs=true
  2. Quando la pagina viene caricata, visualizzate l’origine della pagina.
  3. Fare clic sul collegamento fornito come href per l'elemento di collegamento per aprire il file e visualizzare il codice sorgente.

Utilizzo dei preprocessori

AEM è possibile collegare preprocessori e navi con supporto per YUI Compressor per CSS e JavaScript e Google Closure Compiler (GCC) per JavaScript con YUI impostato AEM preprocessore predefinito.

I preprocessori collegabili consentono un utilizzo flessibile, tra cui:

  • Definizione di ScriptProcessors in grado di elaborare origini di script
  • I processori sono configurabili con opzioni
  • I processori possono essere utilizzati per la minificazione, ma anche per i casi non minati
  • clientlib può definire quale processore utilizzare
NOTA

Per impostazione predefinita, AEM utilizza il compressore YUI. Per un elenco dei problemi noti, consultate la documentazione GitHub del compressore YUI. Il passaggio al compressore GCC per determinati clientlibs può risolvere alcuni problemi rilevati durante l’utilizzo di YUI.

ATTENZIONE

Non inserite una libreria ridotta in una libreria client. Fornite invece la libreria non elaborata e, se è necessaria la minificazione, utilizzate le opzioni dei preprocessori.

Utilizzo

Potete scegliere di configurare la configurazione dei preprocessori per clientlibrary o per tutta la struttura del sistema.

  • Aggiungere le proprietà multivalore cssProcessor e jsProcessor nel nodo clientlibrary
  • Oppure definire la configurazione predefinita del sistema tramite la configurazione HTML Library Manager OSGi

Una configurazione preprocessore sul nodo clientlib ha la precedenza rispetto alla configurazione OSGI.

Formato ed esempi

Formato
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
Compressore YUI per la riduzione CSS e GCC per JS
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
Typescript to Preprocess (Prepara da preelaborare) e poi GCC to Minify and Obfuscate
jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]
Opzioni GCC aggiuntive
failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

Per ulteriori dettagli sulle opzioni GCC, consultare la documentazione GCC.

Imposta minificatore predefinito di sistema

YUI è impostato come minificatore predefinito in AEM. Per modificare questa impostazione in GCC, attenetevi alla procedura seguente.

  1. Vai a Gestione configurazione Apache Felix all'indirizzo (http://<host>:<portY/system/console/configMgr)
  2. Trovare e modificare il Adobe Granite HTML Library Manager.
  3. Abilitare l'opzione Minify (se non è già abilitata).
  4. Impostare il valore Configurazione predefinita processore JS su min:gcc.
    • Le opzioni possono essere passate se separate da un punto e virgola, ad esempio min:gcc;obfuscate=true.
  5. Fare clic su Salva per salvare le modifiche.

In questa pagina

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free