Använda bibliotek på klientsidan på AEM as a Cloud Service

Digitala upplevelser är till stor del beroende av bearbetning på klientsidan som styrs av komplex JavaScript- och CSS-kod. Med AEM-bibliotek (klientbibliotek) kan du ordna och centralt lagra dessa klientbibliotek i databasen. Kopplad med front end build process in the AEM Project Archetype, det blir enkelt att hantera koden för ditt AEM.

Fördelarna med att använda klienter i AEM är bland annat:

  • Kod på klientsidan lagras i databasen precis som all annan programkod och annat innehåll
  • Med Clientlibs in AEM kan du samla all CSS och JS i en enda fil
  • Visa klienten via en bana som är tillgänglig via avsändare
  • Tillåter omskrivning av sökvägar för refererade filer eller bilder

Clientlibs är den inbyggda lösningen för att leverera CSS och Javascript från AEM.

TIPS

Utvecklare som skapar CSS och Javascript för AEM bör också bekanta sig med AEM Project Archetype och dess automatiserade front-end-byggprocess.

Vad är bibliotek på klientsidan?

Webbplatser kräver JavaScript och CSS samt statiska resurser som ikoner och webbteckensnitt för att kunna bearbetas på klientsidan. En klientlib är AEM som refererar (efter kategori om det behövs) och betjänar sådana resurser.

AEM samlar in webbplatsens CSS och Javascript till en enda fil, på en central plats, för att säkerställa att endast en kopia av en resurs inkluderas i utdata från HTML. Detta maximerar effektiviteten vid leverans och gör att sådana resurser kan underhållas centralt i databasen via proxy, vilket skyddar åtkomsten.

Front-End Development för AEM as a Cloud Service

Alla JavaScript-, CSS- och andra front end-resurser ska bevaras i ui.front-modulen i AEM Project Archetype. Tack vare den flexibla arkitekturen kan du använda dina moderna webbverktyg för att skapa och hantera dessa resurser.

Arketypen kan sedan kompilera resurserna till en enda CSS- och JS-fil och bädda in dem automatiskt i en cq:clientLibraryFolder i databasen.

Mappstruktur för klientbibliotek

En biblioteksmapp på klientsidan är en databasnod av typen cq:ClientLibraryFolder. Dess definition i CND-notation är

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple
  • cq:ClientLibraryFolder kan placeras var som helst i /apps underträd till databasen.
  • Använd categories för noden för att identifiera de bibliotekskategorier som den tillhör.

Varje cq:ClientLibraryFolder innehåller en uppsättning JS- och/eller CSS-filer, tillsammans med några stödfiler (se nedan). Viktiga egenskaper för cq:ClientLibraryFolder är konfigurerade enligt följande:

  • allowProxy: Eftersom alla klientlibs måste lagras under apps, tillåter den här egenskapen åtkomst till klientbibliotek via proxyservrar. Se avsnittet Hitta en klientbiblioteksmapp och använda servern för proxyklientbibliotek nedan.
  • categories: Identifierar de kategorier i vilka uppsättningen JS- och/eller CSS-filer i den här cq:ClientLibraryFolder höst. The categories eftersom en biblioteksmapp är flervärdesdel kan den ingå i mer än en kategori (se nedan hur detta kan vara användbart).

Om klientbiblioteksmappen innehåller en eller flera källfiler som sammanfogas till en enda JS- och/eller CSS-fil vid körning. Den genererade filens namn är nodnamnet med antingen .js eller .css filnamnstillägg. Biblioteksnoden med namnet cq.jquery resultat i den genererade filen med namnet cq.jquery.js eller cq.jquery.css.

Klientbiblioteksmappar innehåller följande objekt:

  • JS- och/eller CSS-källfiler
  • Statiska resurser som stöder CSS-format, t.ex. ikoner, webbteckensnitt osv.
  • Ett js.txt fil och/eller en css.txt som identifierar de källfiler som ska sammanfogas i de genererade JS- och/eller CSS-filerna

Clientlib-arkitektur

Skapa biblioteksmappar på klientsidan

Klientbibliotek måste finnas under /apps. Detta för att bättre isolera kod från innehåll och konfiguration.

I ordning för klientbiblioteken under /apps För att vara tillgänglig används en proxyserver. Åtkomstkontrollistorna används fortfarande i klientbiblioteksmappen, men med den kan innehållet läsas via /etc.clientlibs/ om allowProxy egenskapen är inställd på true.

  1. Öppna CRXDE Lite i en webbläsare (https://<host>:<port>/crx/de).
  2. Välj /apps mapp och klicka på Skapa > Skapa nod.
  3. Ange ett namn för biblioteksmappen och i dialogrutan Typ välj lista cq:ClientLibraryFolder. Klicka OK och sedan klicka Spara alla.
  4. Om du vill ange den eller de kategorier som biblioteket tillhör väljer du cq:ClientLibraryFolder lägg till följande egenskap och klicka sedan på Spara alla:
    • Namn: categories
    • Typ: Sträng
    • Värde: Kategorinamnet
    • Flera: Markerad
  5. För att klientbiblioteken ska vara tillgängliga via proxy under /etc.clientlibsväljer du cq:ClientLibraryFolder lägg till följande egenskap och klicka sedan på Spara alla:
    • Namn: allowProxy
    • Typ: Boolean
    • Värde: true
  6. Om du behöver hantera statiska resurser skapar du en undermapp med namnet resources nedanför klientbiblioteksmappen.
    • Om du lagrar statiska resurser var som helst utom under mappen resourceskan de inte refereras till i en publiceringsinstans.
  7. Lägg till källfiler i biblioteksmappen.
    • Detta görs vanligtvis i den inledande byggprocessen för AEM Project Archetype.
    • Du kan ordna källfiler i undermappar om du vill.
  8. Markera klientbiblioteksmappen och klicka på Skapa > Skapa fil.
  9. Skriv något av följande filnamn i rutan Filnamn och klicka på OK:
    • js.txt: Använd det här filnamnet för att generera en JavaScript-fil.
    • css.txt: Använd det här filnamnet för att generera en CSS (Cascading Style Sheet).
  10. Öppna filen och skriv följande text för att identifiera källfilernas rot:
    • #base=*[root]*
    • Ersätt [root] med sökvägen till den mapp som innehåller källfilerna i förhållande till TXT-filen. Använd till exempel följande text när källfilerna finns i samma mapp som TXT-filen:
      • #base=.
    • Följande kod anger roten som mappen mobile under cq:ClientLibraryFolder nod:
      • #base=mobile
  11. På raderna nedan #base=[root]anger du sökvägarna för källfilerna i förhållande till roten. Placera varje filnamn på en separat rad.
  12. Klicka Spara alla.

Serverar bibliotek på klientsidan

När klientbiblioteksmappen är konfigurerad efter behov, dina klienter kan beställas via proxy. Exempel:

  • Du har en klientlib i /apps/myproject/clientlibs/foo
  • Du har en statisk bild i /apps/myprojects/clientlibs/foo/resources/icon.png

The allowProxy kan du begära:

  • Klientlib via /etc.clientlibs/myprojects/clientlibs/foo.js
  • Den statiska bilden via /etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png

Läser in klientbibliotek via HTML

När dina klienter har lagrats och hanterats i klientbiblioteksmappen kan de nås via HTML.

Klientbibliotek läses in via en hjälpmall från AEM, som du kommer åt via data-sly-use. Hjälpmallar är tillgängliga i den här filen, som kan anropas via data-sly-call.

Varje hjälpmall förväntar sig en categories för att referera till önskade klientbibliotek. Det alternativet kan antingen vara en array med strängvärden eller en sträng som innehåller en kommaseparerad värdelista.

Se dokumentationen för HTML om du vill ha mer information om hur du läser in klientlibs via HTML.

Klientbibliotek på författare jämfört med Publicera

De flesta klientlibs krävs i den AEM publiceringsinstansen. Det vill säga, de flesta kundens syften är att skapa en användarupplevelse av innehållet. För clientlibs on publish instances, verktyg för framtagning kan användas och distribueras via klientbiblioteksmappar enligt beskrivningen ovan.

Det finns dock tillfällen då klientbibliotek kan behövas för att anpassa redigeringsupplevelsen. Om du till exempel anpassar en dialogruta kan det krävas att du distribuerar små bitar av CSS eller JS till AEM.

Hantera klientbibliotek på författare

Om du behöver använda klientbibliotek när du är författare kan du skapa dina klientbibliotek under /apps använda samma metoder som för publicering, men skriva direkt under /apps/.../clientlibs/foo i stället för att skapa ett helt projekt för att hantera det.

Du kan sedan"koppla" till JS:t för redigering genom att lägga till dina klientbibliotek i en körklar klientbibliotekskategori.

Felsökningsverktyg

AEM innehåller flera verktyg för felsökning och testning av klientbiblioteksmappar.

Identifiera klientbibliotek

The /libs/cq/granite/components/dumplibs/dumplibs genererar en sida med information om alla klientbiblioteksmappar i systemet. The /libs/granite/ui/content/dumplibs -noden har komponenten som en resurstyp. Om du vill öppna sidan använder du följande URL (ändra värd och port efter behov):

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

Informationen omfattar bibliotekets sökväg och typ (CSS eller JS) samt värdena för biblioteksattributen, t.ex. kategorier och beroenden. Efterföljande tabeller på sidan visar biblioteken i varje kategori och kanal.

Se genererade utdata

The dumplibs -komponenten innehåller en testväljare som visar den källkod som genereras för ui:includeClientLib -taggar. Sidan innehåller kod för olika kombinationer av js-, css- och temaattribut.

  1. Använd någon av följande metoder för att öppna sidan Testa utdata:
    • Från dumplibs.html klickar du på länken på sidan Klicka här för utdatatestning text.
    • Öppna följande URL i webbläsaren (använd en annan värd och port efter behov):
      • http://<host>:<port>/libs/granite/ui/content/dumplibs.html
    • Standardsidan visar utdata för taggar utan värde för attributet categories.
  2. Om du vill visa utdata för en kategori anger du värdet för klientbibliotekets categories egenskap och klicka på Skicka fråga.

Ytterligare funktioner i klientbiblioteksmappen

Det finns ett antal andra funktioner som stöds av klientbiblioteksmappar i AEM. Dessa är dock inte nödvändiga på AEM as a Cloud Service och därför bör de inte användas. De listas här för fullständighetens skull.

VARNING

Dessa extrafunktioner i klientbiblioteksmappar behövs inte på AEM as a Cloud Service och därför bör de inte användas. De listas här för fullständighetens skull.

Bibliotekshanteraren Adobe Granite HTML

Ytterligare inställningar för klientbibliotek kan styras via Bibliotekshanteraren Adobe Granite HTML panelen System Console på https://<host>:<port>/system/console/configMgr).

Ytterligare mappegenskaper

Ytterligare mappegenskaper kan styra beroenden och inbäddningar, men behövs vanligtvis inte längre och användningen bör därför inte användas:

  • dependencies: Det här är en lista över andra klientbibliotekskategorier som den här biblioteksmappen är beroende av. Anges till exempel två cq:ClientLibraryFolder noder F och G, om det finns en fil i F kräver en annan fil i G för att fungera på rätt sätt måste minst en av categories av G ska vara bland dependencies av F.
  • embed: Används för att bädda in kod från andra bibliotek. Om nod F bäddar in noder G och Hblir det resulterande HTML en sammanfogning av innehåll från noder G och H.

Länka till beroenden

När koden i klientbiblioteksmappen refererar till andra bibliotek identifierar du de andra biblioteken som beroenden. The ui:includeClientLib -taggen som refererar till din klientbiblioteksmapp gör att HTML-koden innehåller en länk till den biblioteksfil som genereras samt beroenden.

Beroenden måste vara ett annat cq:ClientLibraryFolder. Om du vill identifiera beroenden lägger du till en egenskap i cq:ClientLibraryFolder nod med följande attribut:

  • Namn: beroenden
  • Typ: Sträng[]
  • Värden: Värdet på egenskapen categories för den cq:ClientLibraryFolder-nod som den aktuella biblioteksmappen är beroende av.

Till exempel /etc/clientlibs/myclientlibs/publicmain är beroende av cq.jquery bibliotek. Sidan som refererar till huvudklientbiblioteket genererar HTML som innehåller följande kod:

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

Bädda in kod från andra bibliotek

Du kan bädda in kod från ett klientbibliotek i ett annat klientbibliotek. Vid körning innehåller de genererade JS- och CSS-filerna för inbäddningsbiblioteket koden för det inbäddade biblioteket.

Inbäddning av kod är användbart för att ge åtkomst till bibliotek som lagras i skyddade områden i databasen.

Appspecifika klientbiblioteksmappar

Det är en god vana att behålla alla programrelaterade filer i programmappen nedan /apps. Det är också en god vana att neka åtkomst för webbplatsbesökare till /apps mapp. Skapa en klientbiblioteksmapp under /etc mapp som bäddar in klientbiblioteket som finns under /apps.

Använd egenskapen categories för att identifiera klientbiblioteksmappen som ska bäddas in. Om du vill bädda in biblioteket lägger du till en egenskap i inbäddningen cq:ClientLibraryFolder nod, med följande egenskapsattribut:

  • Namn: embed
  • Typ: Sträng[]
  • Värde: Värdet för egenskapen categories i cq:ClientLibraryFolder nod att bädda in.

Använda inbäddning för att minimera begäranden

I vissa fall kan det finnas ett relativt stort antal HTML som har skapats för en vanlig sida av publiceringsinstansen <script> -element.

I sådana fall kan det vara användbart att kombinera all nödvändig klientbibliotekskod till en enda fil så att antalet fram- och tillbaka-begäranden vid sidinläsning minskar. För att göra detta kan du embed de nödvändiga biblioteken i ditt programspecifika klientbibliotek med hjälp av egenskapen embed i cq:ClientLibraryFolder nod.

Sökvägar i CSS-filer

När du bäddar in CSS-filer använder den genererade CSS-koden sökvägar till resurser som är relativa till inbäddningsbiblioteket. Till exempel det bibliotek som är tillgängligt för allmänheten /etc/client/libraries/myclientlibs/publicmain bäddar in /apps/myapp/clientlib klientbibliotek:

The main.css filen innehåller följande format:

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

CSS-filen som publicmain noden genererar följande format med den ursprungliga bildens URL:

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

Se Inbäddade filer i utdata från HTML

Om du vill spåra ursprunget för inbäddad kod eller se till att inbäddade klientbibliotek ger det förväntade resultatet, kan du se namnen på de filer som bäddas in under körning. Om du vill se filnamnen lägger du till debugClientLibs=true parametern till webbsidans URL. Biblioteket som skapas innehåller @import -programsatser i stället för den inbäddade koden.

I exemplet i föregående Bädda in kod från andra bibliotek -avsnittet, /etc/client/libraries/myclientlibs/publicmain klientbiblioteksmappen bäddar in /apps/myapp/clientlib biblioteksmapp för klient. Om du lägger till parametern på webbsidan skapas följande länk i webbsidans källkod:

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

Öppna publicmain.css filen visar följande kod:

@import url("/apps/myapp/clientlib/styles/main.css");
  1. Lägg till följande text i URL:en för HTML i webbläsarens adressruta:
    • ?debugClientLibs=true
  2. Visa sidans källa när sidan läses in.
  3. Klicka på länken som anges som href för länkelementet för att öppna filen och visa källkoden.

Använda preprocessorer

AEM gör det möjligt att ansluta till förprocessorer och levereras med stöd för YUI-kompressor för CSS och JavaScript och Google Closure Compiler (GCC) för JavaScript med YUI inställt som AEM standardpreprocessor.

De anslutningsbara preprocessorerna möjliggör flexibel användning, inklusive:

  • Definiera ScriptProcessors som kan bearbeta skriptkällor
  • Processorer kan konfigureras med alternativ
  • Processorer kan användas för miniatyrbilder, men även för icke-miniatyrärenden
  • clientlib kan definiera vilken processor som ska användas
OBSERVERA

Som standard använder AEM YUI-kompressor. Se YUI Compressor GitHub-dokumentation om du vill se en lista över kända fel. Om du växlar till GCC-komprimerare för vissa klienter kan vissa problem som uppstår när du använder YUI lösas.

FÖRSIKTIGHET

Placera inte ett miniatyrbibliotek i ett klientbibliotek. Ange i stället Raw-biblioteket och om miniatyrbilder krävs använder du alternativen för preprocessorerna.

Användning

Du kan välja att konfigurera preprocessorer-konfigurationen per klientbibliotek eller system i hela systemet.

  • Lägg till flervärdesegenskaper cssProcessor och jsProcessor på klientbiblioteksnoden
  • Eller definiera systemets standardkonfiguration via HTML Library Manager OSGi-konfiguration

En preprocessorkonfiguration på klientlib-noden har företräde framför OSGI-konfigurationen.

Format och exempel

Format
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
YUI-kompressor för CSS Minification och GCC för JS
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
Typescript to Preprocess and then GCC to Minify and Obfuscate
jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]
Fler GCC-alternativ
failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

Mer information om GCC-alternativ finns i GCC-dokumentation.

Ange systemstandardminiatyr

YUI anges som standardminifierare i AEM. Följ de här stegen för att ändra detta till GCC.

  1. Gå till Apache Felix Config Manager på (http://<host>:<portY/system/console/configMgr)
  2. Sök och redigera Bibliotekshanteraren Adobe Granite HTML.
  3. Aktivera Minify (om det inte redan är aktiverat).
  4. Ange värdet Standardkonfigurationer för JS-processor till min:gcc.
    • Alternativ kan skickas om de avgränsas med ett semikolon, till exempel min:gcc;obfuscate=true.
  5. Klicka Spara för att spara ändringarna.

På denna sida