在AEM上使用用戶端程式庫做為雲端服務

數位體驗嚴重依賴由複雜JavaScript和CSS程式碼驅動的用戶端處理。 AEM Client-Side Libraries(clientlibs)可讓您組織這些用戶端資料庫並集中儲存在儲存庫中。 再加上AEM Project原型中的前端建置程式,管理AEM專案的前端程式碼變得簡單。

在AEM中使用clientlibs的優點包括:

  • 客戶端代碼與所有其他應用程式碼和內容一樣儲存在儲存庫中
  • AEM中的Clientlibs可將所有CSS和JS匯整為一個檔案
  • 透過可通過dispatcher訪問的路徑來公開clientlibs
  • 允許重寫引用檔案或影像的路徑

Clientlibs是內建的解決方案,可從AEM傳送CSS和Javascript。

秘訣

為AEM專案建立CSS和Javascript的前端開發人員也應熟悉AEM專案原型及其自動化前端建立程式。

什麼是客戶端庫

網站需要JavaScript和CSS,以及靜態資源,例如要在用戶端處理的圖示和網頁字型。 clientlib是AEM的機制,可供參考(視需要依類別)並提供此類資源。

AEM會將網站的CSS和Javascript收集到位於中央位置的單一檔案中,以確保HTML輸出中只包含任何資源的一個副本。 這樣可以最大限度地提高交付效率,並允許通過代理在儲存庫中集中維護這些資源,從而保護訪問安全。

AEM雲端服務前端開發

所有JavaScript、CSS和其他前端資產都應維護在AEM專案原型的ui.frontend模組中。 原型的彈性可讓您使用您選擇的現代化網頁工具來建立和管理這些資源。

然後,原型可將資源編譯為單個CSS和JS檔案,並將它們自動嵌入儲存庫的cq:clientLibraryFolder中。

客戶端庫資料夾結構

客戶端庫資料夾是類型cq:ClientLibraryFolder的儲存庫節點。 其在CND符號中的定義是

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple
  • cq:ClientLibraryFolder 節點可以放置在儲存庫子 /apps 樹內的任意位置。
  • 使用節點的categories屬性來標識它所屬的庫類別。

每個cq:ClientLibraryFolder都會填入一組JS和/或CSS檔案,以及一些支援檔案(請參閱下面)。 cq:ClientLibraryFolder的重要屬性配置如下:

  • allowProxy:由於所有clientlibs都必須儲存在下方, apps因此此屬性允許透過proxy servlet存取clientlibraries。請參閱下面的查找客戶端庫資料夾和使用代理客戶端庫Servlet
  • categories:識別今秋JS和/或CSS檔案集所屬的 cq:ClientLibraryFolder 類別。categories屬性是多值的,允許庫資料夾屬於多個類別的一部分(請參閱下面以瞭解其可能有何用處)。

如果用戶端程式庫資料夾包含一或多個在執行時期會合併為單一JS和/或CSS檔案的來源檔案。 生成的檔案名是具有.js.css檔案名副檔名的節點名。 例如,名為cq.jquery的庫節點將生成名為cq.jquery.jscq.jquery.css的生成檔案。

客戶端庫資料夾包含以下項目:

  • JS和/或CSS來源檔案
  • 支援CSS樣式的靜態資源,例如圖示、網頁字型等。
  • 一個js.txt檔案和/或一個css.txt檔案,用以識別要合併到產生的JS和/或CSS檔案中的來源檔案

Clientlib架構

建立客戶端庫資料夾

客戶端庫必須位於/apps下。 這是為了更好地將程式碼與內容和設定隔離。

為了讓/apps下的客戶機庫可以訪問,使用代理伺服器。 ACL仍在客戶端庫資料夾上強制執行,但是,如果allowProxy屬性設定為true,則servlet允許通過/etc.clientlibs/讀取內容。

  1. 在網頁瀏覽器(https://<host>:<port>/crx/de)中開啟CRXDE Lite。
  2. 選擇/apps資料夾,然後按一下​建立>建立節點
  3. 輸入庫資料夾的名稱,並在​類型​清單中選擇cq:ClientLibraryFolder。 按一下​確定 ,然後按一下​保存全部
  4. 要指定庫所屬的類別或類別,請選擇cq:ClientLibraryFolder節點,添加以下屬性,然後按一下​保存所有:
    • 名稱: categories
    • 類型:字串
    • 值:類別名稱
    • 多重:已選取
  5. 要使客戶端庫可通過/etc.clientlibs下的代理訪問,請選擇cq:ClientLibraryFolder節點,添加以下屬性,然後按一下​保存所有 :
    • 名稱: allowProxy
    • 類型:布林值
    • 值: true
  6. 如果您需要管理靜態資源,請在客戶端庫資料夾下建立一個名為resources的子資料夾。
    • 如果將靜態資源儲存在resources資料夾下,則無法在發佈實例上引用這些資源。
  7. 將源檔案添加到庫資料夾。
  8. 選擇客戶端庫資料夾,然後按一下「建立」>「建立檔案」
  9. 在檔案名框中,鍵入以下檔案名之一,然後按一下確定:
    • js.txt: 使用此檔案名稱產生JavaScript檔案。
    • css.txt:使 用此檔案名生成級聯樣式表。
  10. 開啟檔案並輸入下列文字,以識別來源檔案路徑的根目錄:
    • #base=*[root]*
    • [root]替換為包含源檔案的資料夾的路徑(相對於TXT檔案)。 例如,當源檔案與TXT檔案位於同一資料夾時,請使用以下文本:
      • #base=.
    • 以下代碼將root設定為cq:ClientLibraryFolder節點下名為mobile的資料夾:
      • #base=mobile
  11. #base=[root]下面的行中,鍵入源檔案相對於根檔案的路徑。 將每個檔案名稱放在單獨的行上。
  12. 按一下​保存全部

服務客戶端庫

在根據需要配置客戶端庫資料夾後,可以通過代理請求您的客戶端庫。 例如:

  • 您在/apps/myproject/clientlibs/foo中有clientlib
  • 您的/apps/myprojects/clientlibs/foo/resources/icon.png中有靜態影像

allowProxy屬性可讓您要求:

  • 透過j/etc.clientlibs/myprojects/clientlibs/foo.js的clientlib
  • 透過/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png的靜態影像

透過HTL載入用戶端程式庫

一旦您的客戶端程式庫成功儲存並管理在其用戶端程式庫資料夾中,就可透過HTL存取。

用戶端程式庫是透過AEM提供的輔助範本載入,可透過data-sly-use存取。 此檔案中提供幫助程式模板,可通過data-sly-call調用該模板。

每個幫助模板都需要categories選項來引用所需的客戶端庫。 該選項可以是字串值陣列或包含逗號分隔值清單的字串。

如需透過HTL載入 clientlibs的詳細資訊,請參閱HTL檔案。

作者與發佈上的用戶端程式庫

AEM發佈例項上將需要大部分的clientlibs。 也就是說,大部份的clientlibs目的都是要製作內容的使用者體驗。 對於發佈實例上的clientlibs,前端構建工具可通過客戶端庫資料夾使用和部署,如上所述。

不過,有時可能需要用戶端程式庫來自訂製作體驗。 例如,自訂對話方塊可能需要將CSS或JS的小部份部署至AEM製作例項。

在作者上管理客戶端庫

如果您需要在作者上使用用戶端程式庫,可以使用與發佈相同的方法在/apps下建立用戶端程式庫,但直接在/apps/.../clientlibs/foo下寫入,而不是建立整個專案來管理它。

然後,您可以將用戶端程式庫新增至現成可用的用戶端程式庫類別,以「連結」至編寫JS。

調試工具

AEM提供數種工具來除錯和測試用戶端程式庫資料夾。

Discover客戶端庫

/libs/cq/granite/components/dumplibs/dumplibs元件生成有關係統上所有客戶端庫資料夾的資訊頁。 /libs/granite/ui/content/dumplibs節點將元件作為資源類型。 若要開啟頁面,請使用下列URL(視需要變更主機和連接埠):

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

這些資訊包括程式庫路徑和類型(CSS或JS),以及程式庫屬性的值,例如類別和相依性。 頁面上的後續表格會顯示每個類別和頻道中的程式庫。

請參閱生成的輸出

dumplibs元件包含測試選擇器,顯示為ui:includeClientLib標籤產生的原始碼。 頁面包含js、css和主題屬性不同組合的程式碼。

  1. 使用下列其中一種方法來開啟「測試輸出」頁面:
    • dumplibs.html頁面中,按一下​按一下這裡以輸出測試​文本中的連結。
    • 在網頁瀏覽器中開啟下列URL(視需要使用不同的主機和連接埠):
      • http://<host>:<port>/libs/granite/ui/content/dumplibs.html
    • 預設頁面顯示沒有類別屬性值之標籤的輸出。
  2. 要查看類別的輸出,請鍵入客戶端庫的categories屬性的值,然後按一下​提交查詢

其他客戶端庫資料夾功能

AEM中的用戶端資料庫檔案夾支援許多其他功能。 不過,AEM的雲端服務並不需要這些功能,因此不鼓勵使用這些功能。 此處列出它們是為了實現完整性。

警告

AEM上不需要這些「用戶端資料庫檔案夾」的額外功能,因此不建議使用這些功能。 此處列出它們是為了實現完整性。

Adobe Granite HTML LiBrary Manager

其他用戶端程式庫設定可透過系統主控台(位於https://<host>:<port>/system/console/configMgr)的​Adobe Granite HTML Library Manager​面板加以控制。

其他資料夾屬性

其他資料夾屬性包括允許控制相依性和內嵌式檔案,但通常不再需要,也不建議使用:

  • dependencies:這是此庫資料夾所依賴的其他客戶端庫類別的清單。例如,給定兩個cq:ClientLibraryFolder節點FG,如果F中的檔案需要G中的另一個檔案才能正常工作,則Gcategories中至少一個應位於Fdependencies中。
  • embed:用於從其他程式庫內嵌程式碼。如果節點F嵌入節點GH,則生成的HTML將是節點GH中內容的串連。

連結至相依項

當用戶端程式庫資料夾中的程式碼參考其他程式庫時,請將其他程式庫識別為相依性。 引用用戶端程式庫資料夾的ui:includeClientLib標籤會使HTML程式碼包含您所產生程式庫檔案的連結以及相依性。

相依性必須是另一個cq:ClientLibraryFolder。 要標識相依性,請向cq:ClientLibraryFolder節點添加具有以下屬性的屬性:

  • 名稱:相 依性
  • 類型:字 串[]
  • 值:目 前程式庫資料夾所依賴之cq:ClientLibraryFolder節點的categories屬性值。

例如,/etc/clientlibs/myclientlibs/publicmaincq.jquery庫有相關性。 參考主用戶端程式庫的頁面會產生包含下列程式碼的HTML:

<script src="/etc/clientlibs/foundation/cq.jquery.js?lang=zh-Hant" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js?lang=zh-Hant" type="text/javascript">

從其他程式庫內嵌程式碼

您可以將用戶端程式庫的程式碼內嵌至另一個用戶端程式庫。 在執行時期,內嵌程式庫產生的JS和CSS檔案包含內嵌程式庫的程式碼。

嵌入代碼對於提供對儲存在儲存庫的安全區域中的庫的訪問非常有用。

應用程式特定用戶端程式庫資料夾

將所有應用程式相關檔案保留在其應用程式資料夾/app下方是最佳實務。 此外,拒絕網站訪客存取/app資料夾也是最佳做法。 為滿足這兩種最佳做法,請在/etc資料夾下建立一個客戶端庫資料夾,該資料夾嵌入/app以下的客戶端庫。

使用categories屬性來識別要內嵌的用戶端程式庫資料夾。 要嵌入庫,請使用以下屬性屬性將屬性添加到嵌入cq:ClientLibraryFolder節點:

  • 名稱: embed
  • 類型:字 串[]
  • 值: 要嵌入的節點的類別屬 cq:ClientLibraryFolder 性的值。

使用內嵌功能將要求減至最少

在某些情況下,您可能會發現,您的發佈例項為典型頁面產生的最終HTML包含相對大量的<script>元素。

在這種情況下,將所有必要的用戶端程式庫程式碼結合到單一檔案中,以減少頁面載入時的來回請求數,是很有用的。 若要這麼做,您可以使用cq:ClientLibraryFolder節點的embed屬性,將所需的程式庫embed放入應用程式專用的用戶端程式庫。

CSS檔案中的路徑

當您內嵌CSS檔案時,產生的CSS程式碼會使用與內嵌程式庫相關的資源路徑。 例如,可公開存取的程式庫/etc/client/libraries/myclientlibs/publicmain內嵌於/apps/myapp/clientlib用戶端程式庫:

main.css檔案包含下列樣式:

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

publicmain節點生成的CSS檔案使用原始影像的URL包含以下樣式:

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

請參閱「HTML輸出中的內嵌檔案」

若要追蹤內嵌程式碼的來源,或確保內嵌用戶端程式庫產生預期的結果,您可以在執行時期看到內嵌的檔案名稱。 若要查看檔案名稱,請將debugClientLibs=true參數附加至網頁的URL。 產生的程式庫包含@import陳述式,而非內嵌程式碼。

在上一個從其他庫嵌入代碼部分的示例中,/etc/client/libraries/myclientlibs/publicmain客戶端庫資料夾嵌入/apps/myapp/clientlib客戶端庫資料夾。 將參數附加到網頁會在網頁的原始碼中產生下列連結:

<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css?lang=zh-Hant">

開啟publicmain.css檔案會顯示下列程式碼:

@import url("/apps/myapp/clientlib/styles/main.css");
  1. 在網頁瀏覽器的位址方塊中,將下列文字附加至HTML的URL:
    • ?debugClientLibs=true
  2. 頁面載入時,請檢視頁面來源。
  3. 按一下作為連結元素href提供的連結,以開啟檔案並檢視原始碼。

使用預處理器

AEM允許可插拔的預處理器,並隨附支援UYI Plaxporator的CSS和JavaScript以及Google Closure Compiler(GCC)的JavaScript,而UI已設定為AEM的預處理器。

可插拔的預處理器允許靈活使用,包括:

  • 定義可處理指令碼源的指令碼處理器
  • 處理器可配置選項
  • 處理器可用於微型化,但也可用於非微型化的情況
  • clientlib可以定義要使用哪個處理器
注意

依預設,AEM會使用UYI壓縮器。 有關已知問題的清單,請參見UYI壓縮機GitHub文檔。 切換至特定客戶端的GCC壓縮機可解決使用UY時觀察到的一些問題。

注意

請勿將精簡的程式庫放在用戶端程式庫中。 請改為提供原始程式庫,如果需要精簡,請使用預處理器的選項。

使用狀況

您可以選擇根據客戶端庫或整個系統配置預處理器配置。

  • 在clientlibrary節點上添加多值屬性cssProcessorjsProcessor
  • 或者,透過​HTML Library Manager OSGi組態定義系統預設組態

clientlib節點上的預處理器配置優先於OSGI配置。

格式與範例

格式
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
UYI壓縮器,用於CSS精簡化和GCC for JS
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
鍵入「預處理」,然後「GCC」,將「GCC」輸入為「最小化」和「模糊化」
jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]
其他GCC選項
failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

有關GCC選項的詳細資訊,請參見GCC文檔

設定系統預設管理器

UYI在AEM中設為預設微調字元。 要將此更改為GCC,請執行以下步驟。

  1. 前往Apache Felix Config Manager(http://<host>:<portY/system/console/configMgr)
  2. 尋找並編輯​Adobe Granite HTML Library Manager
  3. 啟用​Minify​選項(如果尚未啟用)。
  4. 將值​JS處理器預設配置​設定為min:gcc
    • 若以分號(例如min:gcc;obfuscate=true
  5. 按一下​保存​保存更改。

本頁內容

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
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now