将AEM上的客户端库用作Cloud Service

数字体验严重依赖由复杂的JavaScript和CSS代码驱动的客户端处理。 AEM客户端库(clientlibs)允许您组织这些客户端库并将其集中存储在存储库中。 与AEM项目原型中的前端构建过程相结合,管理AEM项目的前端代码变得非常简单。

在AEM中使用clientlibs的优势包括:

  • 客户端代码与所有其他应用程序代码和内容一样存储在存储库中
  • AEM中的Clientlib可将所有CSS和JS聚合到一个文件中
  • 通过可通过dispatcher访问的路径公开clientlibs
  • 允许重写引用文件或图像的路径

Clientlibs是用于从AEM交付CSS和Javascript的内置解决方案。

小贴士

为AEM项目创建CSS和Javascript的前端开发人员还应熟悉AEM项目原型及其自动化前端构建过程。

什么是客户端库

站点需要JavaScript和CSS以及静态资源(如要在客户端处理的图标和Web字体)。 clientlib是AEM机制,可引用(如果需要,按类别)并提供此类资源。

AEM将网站的CSS和Javascript收集到一个位于中心位置的文件中,以确保HTML输出中只包含任何资源的一个副本。 这样可最大程度地提高交付效率,并允许通过代理在存储库中集中维护此类资源,从而保持访问安全。

AEM as a ACloud Service的前端开发

所有JavaScript、CSS和其他前端资产都应在AEM项目原型的ui.frontend模块中进行维护。 原型的灵活性允许您使用所选的现代Web工具创建和管理这些资源。

然后,原型可以将资源编译为单个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:由于所有clientlib都必须存储在下, apps因此此属性允许通过代理Servlet访问clientlibraries。请参阅下面的查找客户端库文件夹和使用代理客户端库Servlet
  • categories:标识今秋JS和/或CSS文件集所属的类 cq:ClientLibraryFolder 别。categories属性具有多值,允许库文件夹属于多个类别的一部分(请参阅下文,了解这种属性的用途)。

如果客户端库文件夹包含一个或多个在运行时会合并到单个JS和/或CSS文件中的源文件。 生成的文件的名称是扩展名为.js.css的节点名称。 例如,名为cq.jquery的库节点会生成名为cq.jquery.jscq.jquery.css的生成文件。

客户端库文件夹包含以下项目:

  • JS和/或CSS源文件
  • 支持CSS样式的静态资源,如图标、Web字体等。
  • 一个js.txt文件和/或一个css.txt文件,用于标识要合并到生成的JS和/或CSS文件中的源文件

Clientlib架构

创建客户端库文件夹

客户端库必须位于/apps下。 这是为了更好地将代码与内容和配置隔离开来。

为了访问/apps下的客户端库,请使用代理服务器。 ACL仍对客户端库文件夹强制执行,但如果将allowProxy属性设置为true,则Servlet允许通过/etc.clientlibs/读取内容。

  1. 在Web浏览器中打开CRXDE Lite(https://<host>:<port>/crx/de)。
  2. 选择/apps文件夹,然后单击​创建>创建节点
  3. 输入库文件夹的名称,然后在​Type​列表中选择cq:ClientLibraryFolder。 单击​确定,然后单击​保存全部
  4. 要指定库所属的类别或类别,请选择cq:ClientLibraryFolder节点,添加以下属性,然后单击​Save All:
    • 名称: 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=.
    • 以下代码会将根目录设置为cq:ClientLibraryFolder节点下名为mobile的文件夹:
      • #base=mobile
  11. #base=[root]下面的行中,键入源文件相对于根的路径。 将每个文件名放在单独的行上。
  12. 单击​Save All

提供客户端库

根据需要配置了客户端库文件夹后,可通过代理请求您的客户端库。 例如:

  • /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加 载clientlib的更多详细信息,请参阅HTL文档。

创作与发布上的客户端库

在AEM发布实例上,将需要使用大多数clientlib。 也就是说,大多数clientlibs的目的都是为内容提供最终用户体验。 对于发布实例上的clientlibs,可以通过如上所述的🔗客户端库文件夹来使用和部署前端构建工具

但是,有时可能需要客户端库来自定义创作体验。 例如,自定义对话框可能需要将少量CSS或JS部署到AEM创作实例。

管理作者上的客户端库

如果需要在创作时使用客户端库,可以在/apps下使用与发布相同的方法创建客户端库,但直接在/apps/.../clientlibs/foo下写入,而不是创建整个项目来管理它。

然后,您可以通过将客户端库添加到即装即用的客户端库类别,将其“挂接”到创作JS中。

调试工具

AEM提供了多种工具来调试和测试客户端库文件夹。

发现客户端库

/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页面中,单击​单击此处以进行输出测试​文本中的链接。
    • 在Web浏览器中打开以下URL(根据需要使用其他主机和端口):
      • http://<host>:<port>/libs/granite/ui/content/dumplibs.html
    • 默认页面显示类别属性没有值的标记的输出。
  2. 要查看类别的输出,请键入客户端库categories属性的值,然后单击​Submit Query

其他客户端库文件夹功能

AEM中的客户端库文件夹还支持许多其他功能。 但是,AEM as a Cloud Service并不要求使用这些函数,因此不建议使用它们。 这里列出的是完整的。

警告

AEM as a Cloud Service上不需要客户端库文件夹的这些附加功能,因此不建议使用这些功能。 这里列出的是完整的。

AdobeGranite HTML库管理器

其他客户端库设置可通过系统控制台https://<host>:<port>/system/console/configMgr的​AdobeGranite HTML库管理器​面板进行控制。

其他文件夹属性

其他文件夹属性包括允许控制依赖项和嵌入,但通常不再需要,也不建议使用:

  • dependencies:这是此库文件夹所依赖的其他客户端库类别的列表。例如,给定两个cq:ClientLibraryFolder节点FG时,如果F中的文件需要G中的另一个文件才能正常运行,则Gcategories中至少有一个应位于Fdependencies中。
  • embed:用于嵌入来自其他库的代码。如果节点F嵌入节点GH,则生成的HTML将是节点GH中的内容的串联。

链接到依赖项

当客户端库文件夹中的代码引用其他库时,请将其他库标识为依赖项。 引用客户端库文件夹的ui:includeClientLib标记会导致HTML代码包含指向您生成的库文件的链接以及依赖关系。

依赖项必须是另一个cq:ClientLibraryFolder。 要识别依赖关系,请使用以下属性将属性添加到cq:ClientLibraryFolder节点:

  • 名称: 依赖项
  • 类型: 字符串[]
  • 值: 当前库文件夹所依赖的cq:ClientLibraryFolder节点的类别属性的值。

例如,/etc/clientlibs/myclientlibs/publicmaincq.jquery库具有依赖关系。 引用主客户端库的页面会生成包含以下代码的HTML:

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

嵌入来自其他库的代码

您可以将来自客户端库的代码嵌入到其他客户端库中。 在运行时,嵌入库生成的JS和CSS文件包含嵌入库的代码。

嵌入代码对于提供对存储在存储库安全区域中的库的访问权限非常有用。

特定于应用程序的客户端库文件夹

最佳做法是将所有与应用程序相关的文件保留在其/app下的应用程序文件夹中。 拒绝网站访客访问/app文件夹也是最佳做法。 要满足这两个最佳实践,请在/etc文件夹下创建一个客户端库文件夹,该文件夹嵌入位于/app以下的客户端库。

使用类别属性标识要嵌入的客户端库文件夹。 要嵌入库,请使用以下属性属性将属性添加到嵌入cq:ClientLibraryFolder节点:

  • 名称: 嵌入
  • 类型: 字符串[]
  • 值: 要嵌入的节点的类别属 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">

打开publicmain.css文件会显示以下代码:

@import url("/apps/myapp/clientlib/styles/main.css");
  1. 在Web浏览器的地址框中,将以下文本附加到HTML的URL:
    • ?debugClientLibs=true
  2. 页面加载时,查看页面源。
  3. 单击作为链接元素的href提供的链接以打开文件并查看源代码。

使用预处理器

AEM支持可插拔的预处理器,并支持YUI Compressor for CSS和JavaScript和Google Closure Compiler(GCC) for JavaScript,将YUI设置为AEM默认预处理器。

可插拔预处理器允许灵活使用,包括:

  • 定义可处理脚本源的ScriptProcessors
  • 处理器可通过选项进行配置
  • 处理器可用于缩小,但也可用于未缩小的情况
  • clientlib可定义要使用的处理器
注意

默认情况下,AEM使用YUI压缩程序。 有关已知问题的列表,请参阅YUI Compressor GitHub文档。 在使用YUI时,切换到特定客户端的GCC压缩程序可能会解决一些观察到的问题。

注意

请勿在客户端库中放置缩小的库。 请改为提供原始库,如果需要缩小,请使用预处理器的选项。

使用

您可以选择为每个客户端库或系统范围配置预处理器配置。

  • 在clientlibrary节点上添加多值属性cssProcessorjsProcessor
  • 或通过​HTML库管理器 OSGi配置定义系统默认配置

clientlib节点上的预处理器配置优先于OSGI配置。

格式和示例

格式
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
用于CSS缩小的YUI压缩程序和用于JS的GCC
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
键入前处理,然后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文档

设置系统默认缩小器

在AEM中,YUI设置为默认的缩小符。 要将此代码更改为GCC,请执行以下步骤。

  1. 转到Apache Felix配置管理器(http://<host>:<portY/system/console/configMgr)
  2. 查找并编辑​AdobeGranite HTML库管理器
  3. 启用​Minify​选项(如果尚未启用)。
  4. 将值​JS处理器默认配置​设置为min:gcc
    • 如果使用分号(例如,min:gcc;obfuscate=true
  5. 单击​Save​以保存更改。

在此页面上