数字体验在很大程度上依赖于由复杂的JavaScript和CSS代码驱动的客户端处理。 AEM客户端库(clientlibs)允许您在存储库中组织和集中存储这些客户端库。 与 AEM项目原型中的前端构建过程, 可以轻松管理AEM项目的前端代码。
在AEM中使用clientlibs的优点包括:
Clientlibs是用于从AEM提供CSS和Javascript的内置解决方案。
为AEM项目创建CSS和Javascript的前端开发人员还应熟悉 AEM项目原型及其自动前端构建过程。
站点需要在客户端处理JavaScript和CSS以及静态资源,例如图标和Web字体。 clientlib是一种引用(如果需要,按类别)并为此类资源提供服务的AEM机制。
AEM将站点的CSS和Javascript收集到一个位于中心位置的文件中,以确保HTML输出中只包含任何资源的一个副本。 这样可以最大限度地提高交付效率,并且可以通过代理在存储库中集中维护此类资源,从而确保访问安全。
所有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访问客户端库。 请参阅部分 查找客户端库文件夹并使用代理客户端库Servlet 下面的。categories
:标识此JS和/或CSS文件集所属的类别 cq:ClientLibraryFolder
摔倒。 此 categories
属性是多值属性,允许库文件夹属于多个类别(请参阅下方了解其用处)。如果client library文件夹包含一个或多个源文件,则在运行时,这些文件将合并到单个JS和/或CSS文件中。 生成的文件的名称是节点名称,带有 .js
或 .css
文件扩展名。 例如,库节点命名为 cq.jquery
生成的文件中的结果,名为 cq.jquery.js
或 cq.jquery.css
.
客户端库文件夹包含以下项目:
js.txt
文件和/或一个 css.txt
标识要合并到生成的JS和/或CSS文件中的源文件的文件客户端库必须位于 /apps
. 这是为了更好地将代码与内容和配置隔离开。
对于下的客户端库 /apps
要访问,将使用代理servelt。 仍会在客户端库文件夹上强制执行ACL,但servlet允许通过读取内容 /etc.clientlibs/
如果 allowProxy
属性设置为 true
.
https://<host>:<port>/crx/de
)。/apps
文件夹并单击 创建>创建节点.cq:ClientLibraryFolder
. 单击 确定 然后单击 全部保存.cq:ClientLibraryFolder
节点,添加以下属性,然后单击 全部保存:
categories
/etc.clientlibs
,选择 cq:ClientLibraryFolder
节点,添加以下属性,然后单击 全部保存:
allowProxy
true
resources
客户端库文件夹下方。
resources
,无法在发布实例上引用它们。js.txt
: 使用此文件名可生成JavaScript文件。css.txt
: 使用此文件名可生成层叠样式表。#base=*[root]*
[root]
包含源文件的文件夹的路径(相对于TXT文件)。 例如,当源文件与TXT文件位于同一文件夹时,请使用以下文本:
#base=.
cq:ClientLibraryFolder
节点:
#base=mobile
#base=[root]
,键入源文件相对于根的路径。 将每个文件名放在单独的一行上。一旦您的客户端库文件夹 根据需要进行配置, 可以通过代理请求您的clientlibs。 例如:
/apps/myproject/clientlibs/foo
/apps/myprojects/clientlibs/foo/resources/icon.png
此 allowProxy
属性允许您请求:
/etc.clientlibs/myprojects/clientlibs/foo.js
/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png
一旦您的clientlibs成功存储并管理在其客户端库文件夹中,便可以通过HTL访问它们。
客户端库是通过AEM提供的帮助程序模板加载的,该模板可通过访问 data-sly-use
. 帮助程序模板在此文件中可用,可通过调用 data-sly-call
.
每个帮助程序模板都需要一个 categories
选项来引用所需的客户端库。该选项可以是字符串值的数组,也可以是包含逗号分隔值列表的字符串。
请参阅HTL文档 有关通过HTL加载clientlibs的更多详细信息。
AEM发布实例上需要大多数clientlibs。 也就是说,大多数clientlibs的目的是生成内容的最终用户体验。 对于发布实例上的clientlibs, 前端构建工具 可以通过以下方式使用和部署 客户端库文件夹(如上所述)。
但是,有时可能需要客户端库来自定义创作体验。 例如,自定义对话框可能需要将少量CSS或JS部署到AEM创作实例。
如果您需要在作者上使用客户端库,可以在以下位置创建客户端库: /apps
使用与publish相同的方法,但将其直接写在 /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和主题化属性的不同组合的代码。
dumplibs.html
页面上,单击以下位置中的链接: 单击此处进行输出测试 文本。http://<host>:<port>/libs/granite/ui/content/dumplibs.html
categories
属性并单击 提交查询.AEM中的客户端库文件夹支持许多其他功能。 但是,在AEMas a Cloud Service上不需要这些参数,因此建议不要使用这些参数。 为了完整起见,此处列出了它们。
在AEMas a Cloud Service上不需要客户端库文件夹的这些附加功能,因此建议不要使用这些功能。 为了完整起见,此处列出了它们。
其他客户端库设置可通过 AdobeGraniteHTML库管理器 位于的系统控制台面板 https://<host>:<port>/system/console/configMgr
)。
其他文件夹属性包括允许控制依赖项和嵌入,但通常不再需要这些属性,因此建议不要使用这些属性:
dependencies
:这是此库文件夹所依赖的其他客户端库类别的列表。 例如,给定两个 cq:ClientLibraryFolder
节点 F
和 G
,如果文件位于 F
需要另一个文件 G
为了正常运行,则至少一个 categories
之 G
应该属于 dependencies
之 F
.embed
:用于嵌入其他库中的代码。 If节点 F
嵌入节点 G
和 H
,则生成的HTML将是来自节点的内容连接 G
和 H
.当客户端库文件夹中的代码引用其他库时,请将其他库标识为依赖项。 此 ui:includeClientLib
引用了您的客户端库文件夹的标记会导致HTML代码包含指向生成的库文件以及依赖项的链接。
依赖项必须是另一个 cq:ClientLibraryFolder
. 要识别依赖关系,请将资产添加到 cq:ClientLibraryFolder
节点具有以下属性:
例如, /etc/clientlibs/myclientlibs/publicmain
依赖于 cq.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文件包含嵌入库的代码。
嵌入代码可用于提供对存储在存储库安全区域中的库的访问权限。
最佳实践是将所有与应用程序相关的文件保存在其应用程序文件夹的下方 /apps
. 拒绝网站访客访问 /apps
文件夹。 为满足这两个最佳实践的要求,请在以下位置创建一个客户端库文件夹: /etc
嵌入以下客户端库的文件夹 /apps
.
使用categories属性可标识要嵌入的客户端库文件夹。 要嵌入库,请向嵌入中添加属性 cq:ClientLibraryFolder
节点,使用以下属性属性:
cq:ClientLibraryFolder
要嵌入的节点。在某些情况下,您可能会发现发布实例为典型页面生成的最终HTML包含相对大量的 <script>
元素。
在这种情况下,将所有所需的客户端库代码合并到一个文件中会很有用,从而减少页面加载上的来回请求数。 要执行此操作,您可以 embed
所需的库将放入特定于应用程序的客户端库中,使用的嵌入属性 cq:ClientLibraryFolder
节点。
嵌入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%;
}
CSS文件, publicmain
节点使用原始图像的URL生成包含以下样式:
body {
padding: 0;
margin: 0;
background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
width: 100%;
}
要跟踪嵌入代码的来源,或确保嵌入的客户端库产生预期结果,您可以在运行时查看嵌入文件的名称。 要查看文件名,请附加 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");
?debugClientLibs=true
AEM允许使用可插拔的预处理器,并且附带支持 YUI压缩程序 适用于CSS和JavaScript和 Google Closure Compiler (GCC) YUI设置为AEM默认预处理器的JavaScript。
可插拔预处理器允许灵活使用,包括:
默认情况下,AEM使用YUI压缩程序。 请参阅 YUI压缩程序GitHub文档 以获取已知问题的列表。 为特定clientlibs切换到GCC压缩器可以解决使用YUI时观察到的一些问题。
请勿将缩小的库放置在客户端库中。 而是提供原始库,如果需要缩小,请使用预处理器的选项。
您可以选择按clientlibrary或系统范围配置预处理器配置。
cssProcessor
和 jsProcessor
在客户端库节点上clientlib节点上的预处理器配置优先于OSGI配置。
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
jsProcessor: [
"default:typescript",
"min:typescript",
"min:gcc;obfuscate=true"
]
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,请执行以下步骤。
http://<host>:<portY/system/console/configMgr
)min:gcc
.
min:gcc;obfuscate=true
.