Client-Side Libraries gebruiken op AEM as a Cloud Service

Laatst bijgewerkt: 5 februari 2025

Gemaakt voor:

  • Beheerder
  • Ontwikkelaar

Digitale ervaringen zijn sterk afhankelijk van verwerking op de client door complexe JavaScript- en CSS-code. AEM Client-Side Libraries (clientlibs) kunt u deze clientbibliotheken organiseren en centraal opslaan in de opslagplaats. Gekoppeld aan front-end bouwt proces in het AEM archetype van het Project, wordt het beheren van uw front-end code voor uw AEM project eenvoudig.

Tot de voordelen van het gebruik van clientlibs in AEM behoren:

  • Client-side code wordt net als alle andere toepassingscode en inhoud in de repository opgeslagen
  • Clientlibs in AEM kunnen alle CSS en JS in één bestand samenvoegen
  • Maak clientlibs via een weg bloot die door verzendertoegankelijk is
  • Hiermee kunt u paden herschrijven voor bestanden of afbeeldingen waarnaar wordt verwezen

Clientlibs zijn de ingebouwde oplossing voor het leveren van CSS en JavaScript van AEM.

TIP
De ontwikkelaars van het front-end die CSS en JavaScript voor AEM projecten creëren zouden zich met het AEM Archetype van het Project en zijn geautomatiseerd front-end bouwstijlprocesook moeten vertrouwd maken.

Wat zijn clientbibliotheken?

Voor sites moeten JavaScript- en CSS-bronnen en statische bronnen, zoals pictogrammen en weblettertypen, op de client worden verwerkt. Een clientlib AEM het mechanisme om (indien nodig per categorie) te verwijzen en dergelijke middelen te dienen.

AEM verzamelt de CSS en JavaScript van de site in één bestand, op een centrale locatie, om ervoor te zorgen dat er maar één kopie van een bron wordt opgenomen in de HTML-uitvoer. Hierdoor wordt de efficiëntie van de levering gemaximaliseerd en kunnen dergelijke bronnen centraal in de opslagplaats worden onderhouden via proxy, zodat de toegang veilig blijft.

Front-end ontwikkeling voor AEM as a Cloud Service

Alle JavaScript, CSS, en andere front-end activa zouden in de {🔗 moeten worden gehandhaafd module 0} ui.frontend van het Archetype van het Project van de AEM. Dankzij de flexibiliteit van het archetype kunt u uw moderne webgereedschappen gebruiken om deze bronnen te maken en te beheren.

Het archetype kan de bronnen vervolgens compileren in één CSS- en JS-bestand en deze automatisch insluiten in een cq:clientLibraryFolder in de opslagplaats.

Structuur van bibliotheekmap op de client

Een bibliotheekmap op de client is een opslagplaats van het type cq:ClientLibraryFolder . Zijn definitie in aantekening CNDis

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple
  • cq:ClientLibraryFolder -knooppunten kunnen overal in de /apps -substructuur van de opslagplaats worden geplaatst.
  • Gebruik de eigenschap categories van het knooppunt om de bibliotheekcategorieën te identificeren waartoe het behoort.

Elke cq:ClientLibraryFolder wordt gevuld met een set JS- en/of CSS-bestanden, samen met enkele ondersteunende bestanden (zie hieronder). Belangrijke eigenschappen van de cq:ClientLibraryFolder zijn als volgt geconfigureerd:

Als de map met clientbibliotheken een of meer bronbestanden bevat die tijdens runtime worden samengevoegd tot één JS- en/of CSS-bestand. De naam van het gegenereerde bestand is de knooppuntnaam met de bestandsnaamextensie .js of .css . Het bibliotheekknooppunt cq.jquery resulteert bijvoorbeeld in het gegenereerde bestand met de naam cq.jquery.js of cq.jquery.css .

Clientbibliotheekmappen bevatten de volgende items:

  • JS- en/of CSS-bronbestanden
  • Statische bronnen die CSS-stijlen ondersteunen, zoals pictogrammen, weblettertypen, enzovoort.
  • Eén js.txt -bestand en/of één css.txt -bestand met de bronbestanden die moeten worden samengevoegd in de gegenereerde JS- en/of CSS-bestanden

Clientlib architectuur

Clientzijbibliotheekmappen maken

Clientbibliotheken moeten zich onder /apps bevinden. Deze regel is nodig om code beter te isoleren van inhoud en configuratie.

De clientbibliotheken onder /apps zijn alleen toegankelijk als er een proxyserver wordt gebruikt. ACLs wordt nog afgedwongen op de omslag van de cliëntbibliotheek, maar servlet staat voor de inhoud toe om via /etc.clientlibs/ worden gelezen als het allowProxy bezit aan true wordt geplaatst.

  1. Open CRXDE Lite in Webbrowser (https://<host>:<port>/crx/de).

  2. Selecteer de /apps omslag en klik creëren > Node creëren.

  3. Ga een naam voor de bibliotheekomslag in, en in de Uitgezochte lijst van het Type cq:ClientLibraryFolder. Klik O.K. en klik dan sparen allen.

  4. Om de categorie of de categorieën te specificeren dat de bibliotheek tot behoort, selecteer de cq:ClientLibraryFolder knoop, voeg het volgende bezit toe, en klik dan sparen allen:

    • Naam: categories
    • Type: String
    • Waarde: de categorienaam
    • Meerdere: geselecteerd

  5. Opdat de cliëntbibliotheken via volmacht onder /etc.clientlibs toegankelijk zijn, selecteer de cq:ClientLibraryFolder knoop, voeg het volgende bezit toe, en klik dan sparen allen:

    • Naam: allowProxy
    • Type: Boolean
    • Waarde: true

  6. Als u statische bronnen moet beheren, maakt u een submap met de naam resources onder de clientbibliotheekmap.

    • Als u statische bronnen ergens anders opslaat dan in de map resources , kan er niet naar worden verwezen op een publicatie-instantie.

  7. Bronbestanden toevoegen aan de bibliotheekmap.

    • Dit wordt typisch gedaan door het front-end bouwstijlproces van AEM Archetype van het Project.
    • U kunt bronbestanden desgewenst in submappen ordenen.

  8. Selecteer de omslag van de cliëntbibliotheek en klik creëren > dossier creëren.

  9. Typ in het vak Bestandsnaam een van de volgende bestandsnamen en klik op OK:

    • js.txt: gebruik deze bestandsnaam om een JavaScript-bestand te genereren.
    • css.txt: gebruik deze bestandsnaam om een trapsgewijs opmaakmodel te genereren.

  10. Open het bestand en typ de volgende tekst om de hoofdmap van het pad van de bronbestanden te identificeren:

    • #base=*[root]*
    • Vervang [root] door het pad naar de map met de bronbestanden, relatief ten opzichte van het TXT-bestand. Gebruik bijvoorbeeld de volgende tekst wanneer de bronbestanden zich in dezelfde map bevinden als het TXT-bestand:
      • #base=.
    • Met de volgende code wordt de hoofdmap ingesteld als de map met de naam mobile onder het knooppunt cq:ClientLibraryFolder :
      • #base=mobile

  11. Typ op de onderstaande regels #base=[root] de paden van de bronbestanden ten opzichte van het hoofdbestand. Plaats elke bestandsnaam op een aparte regel.

  12. Klik sparen allen.

Client-Side bibliotheken bedienen

Zodra uw omslag van de cliëntbibliotheek zoals vereistwordt gevormd, kunnen uw clientlibs via volmacht worden gevraagd. Als voorbeeld:

  • U hebt een clientlib in /apps/myproject/clientlibs/foo
  • U hebt een statische afbeelding in /apps/myprojects/clientlibs/foo/resources/icon.png

Met de eigenschap allowProxy kunt u het volgende aanvragen:

  • Clientlib via /etc.clientlibs/myprojects/clientlibs/foo.js
  • De statische afbeelding via /etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png

Clientbibliotheken laden via HTML

Zodra uw clientbibliotheken zijn opgeslagen en beheerd in hun clientbibliotheekmap, kunnen ze toegang krijgen via HTML.

Clientbibliotheken worden geladen via een helpersjabloon die door AEM wordt geboden en die toegankelijk is via data-sly-use . De hulpmalplaatjes zijn beschikbaar in dit dossier, dat door data-sly-call kan worden geroepen.

Elke hulpsjabloon verwacht een categories optie voor het verwijzen naar de gewenste clientbibliotheken. Deze optie kan ofwel een array van tekenreekswaarden zijn, ofwel een tekenreeks met een lijst met door komma's gescheiden waarden.

zie de documentatie HTMLvoor meer details bij het laden van clientlibs via HTML.

Client-bibliotheken op auteur versus Publish

De meeste clientlibs zijn vereist op de AEM-publicatie-instantie. Dat wil zeggen dat de meeste clientlibs-doeleinden de eindgebruikerservaring van de inhoud moeten opleveren. Voor clientlibs op publiceer instanties, front-end bouwt hulpmiddelenkan worden gebruikt en via omslagen van de cliëntbibliotheek zoals hierboven beschrevenworden opgesteld.

Er zijn echter momenten waarop clientbibliotheken nodig kunnen zijn om de ontwerpervaring aan te passen. Als u bijvoorbeeld een dialoogvenster aanpast, moet u mogelijk kleine CSS- of JS-bits implementeren in de AEM ontwerpinstantie.

Clientbibliotheken beheren op auteur

Als u clientbibliotheken op de auteur wilt gebruiken, kunt u onder /apps uw clientbibliotheken maken met dezelfde methoden als voor publiceren, maar deze rechtstreeks onder /apps/.../clientlibs/foo schrijven in plaats van een geheel project te maken om het te beheren.

U kunt dan "haken"in auteursJS door uw cliëntbibliotheken aan een uit-van-de-doos categorie van de cliëntbibliotheek toe te voegen.

Foutopsporingsgereedschappen

AEM beschikt over verschillende gereedschappen voor foutopsporing en het testen van clientbibliotheekmappen.

Clientbibliotheken detecteren

De component /libs/cq/granite/components/dumplibs/dumplibs genereert een pagina met informatie over alle clientbibliotheekmappen op het systeem. Het knooppunt /libs/granite/ui/content/dumplibs heeft de component als een brontype. Als u de pagina wilt openen, gebruikt u de volgende URL (waarbij u de host en poort naar wens wijzigt):

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

Tot de gegevens behoren het bibliotheekpad en -type (CSS of JS) en de waarden van de bibliotheekkenmerken, zoals categorieën en afhankelijkheden. In de volgende tabellen op de pagina worden de bibliotheken in elke categorie en elk kanaal weergegeven.

Zie Gegenereerde uitvoer

De component dumplibs bevat een testkiezer die de broncode weergeeft die voor ui:includeClientLib -tags wordt gegenereerd. De pagina bevat code voor verschillende combinaties van js-, css- en themakenmerken.

  1. Gebruik een van de volgende methoden om de pagina Uitvoer testen te openen:

    • Van de dumplibs.html pagina, klik de verbinding in klik hier voor output het testen tekst.
    • Open de volgende URL in uw webbrowser (gebruik indien nodig een andere host en poort):
      • http://<host>:<port>/libs/granite/ui/content/dumplibs.html
    • Op de standaardpagina wordt uitvoer weergegeven voor tags zonder waarde voor het categoriekenmerk.

  2. Om de output voor een categorie te zien, typ de waarde van het bezit van de cliëntbibliotheek categories en klik voorleggen Vraag.

Extra functies voor clientbibliotheekmappen

Er zijn verscheidene andere eigenschappen die door de omslagen van de cliëntbibliotheek in AEM worden gesteund. Deze zijn echter niet verplicht voor AEM as a Cloud Service en daarom wordt het gebruik ervan afgeraden. Zij worden hier vermeld voor volledigheid.

WARNING
Deze extra functies van clientbibliotheekmappen zijn niet vereist op AEM as a Cloud Service en daarom wordt het gebruik ervan afgeraden. Zij worden hier vermeld voor volledigheid.

Adobe Granite HTML Library Manager

De extra montages van de cliëntbibliotheek kunnen door het Adobe Granite Manager van de Bibliotheek van de HTML paneel van de Console van het Systeem bij https://<host>:<port>/system/console/configMgr worden gecontroleerd.

Extra mapeigenschappen

De extra omslageigenschappen omvatten staan controle van gebiedsdelen en bedden toe, maar zijn over het algemeen niet meer nodig en hun gebruik wordt ontmoedigd:

  • dependencies: Dit is een lijst met andere categorieën in de clientbibliotheek waarvan deze bibliotheekmap afhankelijk is. Als een bestand in F bijvoorbeeld een ander bestand in G nodig heeft om correct te werken, moet op basis van twee cq:ClientLibraryFolder nodes F en G ten minste een van de categories of G -knooppunten deel uitmaken van de dependencies of F -lus.
  • embed: wordt gebruikt om code uit andere bibliotheken in te sluiten. Als knooppunt F knooppunten G en H insluit, is de resulterende HTML een samenvoeging van inhoud van knooppunten G en H .

Koppeling naar afhankelijke instellingen

Wanneer de code in de map met clientbibliotheken verwijst naar andere bibliotheken, identificeert u de andere bibliotheken als afhankelijkheden. De tag ui:includeClientLib die verwijst naar de map van de clientbibliotheek zorgt ervoor dat de HTML-code een koppeling bevat naar het gegenereerde bibliotheekbestand en de afhankelijkheden.

De afhankelijkheden moeten een andere cq:ClientLibraryFolder zijn. Om gebiedsdelen te identificeren, voeg een bezit aan uw cq:ClientLibraryFolder knoop met de volgende attributen toe:

  • Naam: gebiedsdelen
  • Type: Koord []
  • Waarden: de waarde van het categoriereigenschap van de cq:ClientLibraryFolder knoop die de huidige bibliotheekomslag van afhangt.

De /etc/clientlibs/myclientlibs/publicmain is bijvoorbeeld afhankelijk van de cq.jquery -bibliotheek. De pagina die verwijst naar de hoofdclientbibliotheek genereert een HTML die de volgende code bevat:

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

Code van andere bibliotheken insluiten

U kunt code van een clientbibliotheek insluiten in een andere clientbibliotheek. Tijdens de runtime bevatten de gegenereerde JS- en CSS-bestanden van de insluitingsbibliotheek de code van de ingesloten bibliotheek.

Het insluiten van code is handig voor het verschaffen van toegang tot bibliotheken die zijn opgeslagen in beveiligde gebieden van de opslagplaats.

Toepassingsspecifieke clientbibliotheekmappen

U kunt het beste alle toepassingsgerelateerde bestanden in hun toepassingsmap onder /apps houden. Het wordt ook aanbevolen bezoekers van websites toegang tot de map /apps te weigeren. Voor beide aanbevolen procedures maakt u een clientbibliotheekmap onder de map /etc die de clientbibliotheek onder /apps insluit.

Gebruik de eigenschap Categorieën om de clientbibliotheekmap te identificeren die u wilt insluiten. Als u de bibliotheek wilt insluiten, voegt u een eigenschap toe aan het insluitingsknooppunt cq:ClientLibraryFolder en gebruikt u de volgende eigenschapkenmerken:

  • Naam: bed in
  • Type: Koord []
  • Waarde: de waarde van het categoriebezit van de cq:ClientLibraryFolder knoop in te bedden.

Insluiten gebruiken om verzoeken te minimaliseren

In sommige gevallen zult u zien dat de uiteindelijke HTML die door uw publicatieexemplaar wordt gegenereerd voor een standaardpagina, een relatief groot aantal <script> -elementen bevat.

In dergelijke gevallen kan het handig zijn om alle vereiste code van de clientbibliotheek te combineren in één bestand, zodat het aantal heen en weer aanvragen bij het laden van de pagina wordt verminderd. Hiervoor kunt u embed de vereiste bibliotheken in uw toepassingsspecifieke clientbibliotheek plaatsen met de eigenschap embed van het knooppunt cq:ClientLibraryFolder .

Paden in CSS-bestanden

Wanneer u CSS-bestanden insluit, gebruikt de gegenereerde CSS-code paden naar bronnen die relatief zijn ten opzichte van de insluitingsbibliotheek. De openbaar toegankelijke bibliotheek /etc/client/libraries/myclientlibs/publicmain sluit bijvoorbeeld de /apps/myapp/clientlib -clientbibliotheek in:

Het bestand main.css bevat de volgende stijl:

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

Het CSS-bestand dat de node publicmain genereert, bevat de volgende stijl met behulp van de URL van de oorspronkelijke afbeelding:

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

Zie Ingesloten bestanden in HTML-uitvoer

Als u de oorsprong van ingesloten code wilt traceren of wilt controleren of ingesloten clientbibliotheken de verwachte resultaten opleveren, kunt u de namen zien van de bestanden die bij uitvoering worden ingesloten. Als u de bestandsnamen wilt zien, voegt u de parameter debugClientLibs=true toe aan de URL van de webpagina. De gegenereerde bibliotheek bevat @import -instructies in plaats van de ingesloten code.

In het voorbeeld in het vorige Inbedden Code van Andere Bibliothekensectie, sluit de /etc/client/libraries/myclientlibs/publicmain omslag van de cliëntbibliotheek de /apps/myapp/clientlib omslag van de cliëntbibliotheek in. Als u de parameter aan de webpagina toevoegt, wordt de volgende koppeling in de broncode van de webpagina gemaakt:

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

Wanneer u het publicmain.css -bestand opent, wordt de volgende code weergegeven:

@import url("/apps/myapp/clientlib/styles/main.css");
  1. Voeg in het adresvak van uw webbrowser de volgende tekst toe aan de URL van uw HTML:
    • ?debugClientLibs=true
  2. Bekijk de paginabron wanneer de pagina wordt geladen.
  3. Klik op de koppeling die wordt opgegeven als de href voor het koppelingselement om het bestand te openen en de broncode weer te geven.

Voorprocessors gebruiken

AEM staat voor pluggable preprocessoren en schepen met steun voor Compressor YUIvoor CSS en JavaScript toe en de Compiler van de Sluiting van Google (GCC)voor JavaScript met YUI die als AEM standaard preprocessor wordt geplaatst.

Met de aanpasbare voorprocessoren kunt u flexibel gebruik maken, waaronder:

  • ScriptProcessors definiëren die scriptbronnen kunnen verwerken
  • Processors kunnen worden geconfigureerd met opties
  • Processors kunnen worden gebruikt voor minificatie, maar ook voor niet-minieme gevallen
  • Clientlib kan bepalen welke processor moet worden gebruikt
NOTE
AEM gebruikt standaard de YUI-compressor. Zie de documentatie van GitHub van de Compressor van YUIvoor een lijst van bekende kwesties. Het schakelen naar GCC-compressor voor bepaalde clientlibs kan een aantal problemen oplossen die tijdens het gebruik van YUI zijn waargenomen.
CAUTION
Plaats geen geminiateerde bibliotheek in een clientbibliotheek. Geef in plaats daarvan de onbewerkte bibliotheek op en gebruik de opties van de voorprocessoren als miniatuurafbeelding vereist is.

Gebruik

U kunt kiezen om de configuratie van preprocessoren per clientbibliotheek of systeembreed te configureren.

  • De eigenschappen multivalue cssProcessor en jsProcessor toevoegen aan het clientbibliotheekknooppunt
  • Of bepaal de systeem standaardconfiguratie via de configuratie OSGi van de Manager van de Bibliotheek 0} HTML

Een preprocessorconfiguratie op de clientlib knoop neemt belangrijkheid over de configuratie OSGI.