客户端库和前端工作流 client-side-libraries

了解如何使用客户端库或clientlibs为Adobe Experience Manager (AEM) Sites实施部署和管理CSS和JavaScript。 本教程还介绍了 ui.frontend 模块,解耦 webpack 项目,可以集成到端到端构建过程中。

前提条件 prerequisites

查看所需的工具和设置说明 本地开发环境.

此外,还建议查看 组件基础知识 教程以了解客户端库和AEM的基础知识。

入门项目

NOTE
如果成功完成了上一章,则可以重用该项目并跳过签出入门项目的步骤。

查看本教程所基于的基本行代码:

  1. 查看 tutorial/client-side-libraries-start 分支自 GitHub

    code language-shell
    $ cd aem-guides-wknd
    $ git checkout tutorial/client-side-libraries-start
    
  2. 使用您的Maven技能将代码库部署到本地AEM实例:

    code language-shell
    $ mvn clean install -PautoInstallSinglePackage
    
    note note
    NOTE
    如果使用AEM 6.5或6.4,请附加 classic 配置文件到任何Maven命令。
    code language-shell
    $ mvn clean install -PautoInstallSinglePackage -Pclassic
    

您始终可以在上查看完成的代码 GitHub 或者切换到分支机构在本地签出代码 tutorial/client-side-libraries-solution.

目标

  1. 了解如何通过可编辑的模板将客户端库包含在页面中。
  2. 了解如何使用 ui.frontend 模块和一个webpack开发服务器,用于专用前端开发。
  3. 了解将编译后的CSS和JavaScript交付到Sites实施的端到端工作流程。

您即将构建的内容 what-build

在本章中,您将为WKND站点和文章页面模板添加一些基线样式,以使实施更接近 UI设计模型. 您可以使用高级前端工作流将webpack项目集成到AEM客户端库中。

完成的样式

应用了基线样式的文章页面

背景 background

客户端库提供了一种机制,用于组织和管理AEM Sites实施所需的CSS和JavaScript文件。 客户端库或clientlibs的基本目标是:

  1. 将CSS/JS存储在小型离散文件中,以方便开发和维护
  2. 以有条理的方式管理对第三方框架的依赖项
  3. 通过将CSS/JS关联到一个或两个请求中,最大程度地减少客户端请求的数量。

有关使用的更多信息 可以在此处找到客户端库。

客户端库确实存在一些限制。 最值得注意的是,对常用前端语言(如Sass、LESS和TypeScript)的支持有限。 在本教程中,我们来了解一下 ui.frontend 模块可以帮助解决此问题。

将入门级代码库部署到本地AEM实例,并导航到 http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html. 此页面未设置样式。 让我们实施适用于WKND品牌的客户端库以将CSS和JavaScript添加到页面。

客户端库组织 organization

接下来,我们来探索由生成的clientlibs的组织结构。 AEM项目原型.

高级客户端库组织

客户端库组织和页面包含概要图

NOTE
以下客户端库组织由AEM Project Archetype生成,但仅代表起点。 项目最终如何向Sites实施管理和提供CSS和JavaScript,可能会因资源、技能集和要求而存在很大差异。
  1. 使用VSCode或其他IDE打开 ui.apps 模块。

  2. 展开路径 /apps/wknd/clientlibs 查看原型生成的clientlibs。

    ui.apps中的Clientlibs

    在以下部分中,将详细审查这些clientlibs。

  3. 下表汇总了客户端库。 更多有关 包括客户端库可在此处找到.

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
    名称 描述 注释
    clientlib-base WKND站点正常运行所需的CSS和JavaScript的基本级别 嵌入核心组件客户端库
    clientlib-grid 生成所需的CSS 布局模式 去工作。 可在此处配置移动设备/平板电脑断点
    clientlib-site 包含WKND站点的站点特定主题 生成者 ui.frontend 模块
    clientlib-dependencies 嵌入任何第三方依赖项 生成者 ui.frontend 模块
  4. 请观察 clientlib-siteclientlib-dependencies 从源代码管理中忽略。 这是特意设计的,因为这些在构建时由 ui.frontend 模块。

更新基本样式 base-styles

接下来,更新在 ui.frontend 模块。 中的文件 ui.frontend 模块生成 clientlib-siteclientlib-dependecies 包含站点主题和任何第三方依赖项的库。

客户端库不支持更高级的语言,例如 萨斯TypeScript. 有多种开源工具,例如 npmwebpack 可以加速和优化前端开发。 的目标 ui.frontend 模块能够使用这些工具来管理大多数前端源文件。

  1. 打开 ui.frontend 模块并导航到 src/main/webpack/site.

  2. 打开文件 main.scss

    main.scss — 入口点

    main.scss 是中Sass文件的入口点 ui.frontend 模块。 它包括 _variables.scss 文件,其中包含一系列要在项目中的不同Sass文件中使用的品牌变量。 此 _base.scss 文件也包含在内,并为HTML元素定义了某些基本样式。 正则表达式包含 src/main/webpack/components. 另一个正则表达式包含下列文件 src/main/webpack/site/styles.

  3. Inspect文件 main.ts. 它包括 main.scss 和正则表达式,用于收集任意 .js.ts 文件中的文件。 此入口点由 webpack配置文件 作为整个网络的入口点 ui.frontend 模块。

  4. Inspect下面的文件 src/main/webpack/site/styles

    样式文件

    这些文件用于模板中的全局元素,如页眉、页脚和主内容容器。 这些文件中的CSS规则以不同的HTML元素为目标 headermain、和 footer. 这些HTML元素由上一章中的策略定义 页面和模板.

  5. 展开 components 文件夹在 src/main/webpack 并检查文件。

    组件Sass文件

    每个文件都映射到核心组件,如 折叠组件. 每个核心组件都使用 块元素修饰符 或BEM表示法,以便更轻松地使用样式规则定位特定的CSS类。 下面的文件 /components 已被AEM项目原型清除,每个组件具有不同的BEM规则。

  6. 下载WKND基本样式 wknd-base-styles-src-v3.zipunzip 文件。

    WKND基本样式

    为了加速教程,提供了多个基于核心组件和文章页面模板的结构实施WKND品牌的Sass文件。

  7. 覆盖的内容 ui.frontend/src ,其中包含上一步骤中的文件。 zip文件的内容应覆盖以下文件夹:

    code language-plain
    /src/main/webpack
             /components
             /resources
             /site
             /static
    

    更改的文件

    Inspect更改的文件,以查看WKND样式实施的详细信息。

Inspect与ui.frontend集成 ui-frontend-integration

内置于中的一个关键集成部分 ui.frontend 模块, aem-clientlib-generator 从webpack/npm项目中获取编译的CSS和JS工件,并将其转换为AEM客户端库。

ui.frontend架构集成

AEM项目原型会自动设置此集成。 接下来,探索它的工作方式。

  1. 打开命令行终端并安装 ui.frontend 模块使用 npm install 命令:

    code language-shell
    $ cd ~/code/aem-guides-wknd/ui.frontend
    $ npm install
    
    note note
    NOTE
    npm install 只需运行一次,例如在新的克隆或生成项目后。
  2. 在中启动webpack开发服务器 观看 模式,运行以下命令:

    code language-shell
    $ npm run watch
    
  3. 这将编译源文件 ui.frontend 模块并将更改与AEM同步,网址为 http://localhost:4502

    code language-shell
    + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
    + jcr_root/apps/wknd/clientlibs/clientlib-site/js
    + jcr_root/apps/wknd/clientlibs/clientlib-site
    + jcr_root/apps/wknd/clientlibs/clientlib-dependencies/css.txt
    + jcr_root/apps/wknd/clientlibs/clientlib-dependencies/js.txt
    + jcr_root/apps/wknd/clientlibs/clientlib-dependencies
    http://admin:admin@localhost:4502 > OK
    + jcr_root/apps/wknd/clientlibs/clientlib-site/css
    + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
    http://admin:admin@localhost:4502 > OK
    
  4. 命令 npm run watch 最终填充 clientlib-siteclientlib-dependenciesui.apps 模块,随后会自动与AEM同步。

    note note
    NOTE
    此外, npm run prod 用于缩小JS和CSS的配置文件。 这是通过Maven触发Webpack构建时的标准编译。 更多有关 可在此处找到ui.frontend模块.
  5. Inspect文件 site.cssui.frontend/dist/clientlib-site/site.css. 这是基于Sass源文件的编译的CSS。

    分布式站点CSS

  6. Inspect文件 ui.frontend/clientlib.config.js. 这是npm插件的配置文件, aem-clientlib-generator 转换的内容 /dist 移入客户端库,并将其移至 ui.apps 模块。

  7. Inspect文件 site.cssui.apps 模块位于 ui.apps/src/main/content/jcr_root/apps/wknd/clientlibs/clientlib-site/css/site.css. 这应该是 site.css 文件来自 ui.frontend 模块。 现在它进去了 ui.apps 模块,可将其部署到AEM。

    ui.apps clientlib-site

    note note
    NOTE
    clientlib-site 在构建期间使用以下任一方法编译: npm,或 maven ​中,可以从源代码管理中安全地忽略它 ui.apps 模块。 Inspect .gitignore 文件在下 ui.apps.
  8. 在AEM中打开LA Skatepark文章,网址为: http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html.

    更新了文章的基本样式

    此时,您应该会看到该文章的更新样式。 您可能需要进行硬刷新以清除浏览器缓存的任何CSS文件。

    它看起来越来越接近模型了!

    note note
    NOTE
    当从项目的根触发Maven构建时,会自动执行以上为构建并将ui.frontend代码部署到AEM而执行的步骤 mvn clean install -PautoInstallSinglePackage.

更改样式

接下来,在 ui.frontend 模块查看 npm run watch 自动将样式部署到本地AEM实例。

  1. 从, ui.frontend 模块打开文件: ui.frontend/src/main/webpack/site/_variables.scss.

  2. 更新 $brand-primary 颜色变量:

    code language-scsss
    //== variables.css
    
    //== Brand Colors
    $brand-primary:          $pink;
    

    保存更改。

  3. 返回浏览器并刷新AEM页面以查看更新:

    客户端库

  4. 将更改恢复为 $brand-primary 使用命令设置颜色并停止webpack构建 CTRL+C.

CAUTION
对的使用 ui.frontend 模块可能并非对所有项目都需要。 此 ui.frontend 模块增加了额外的复杂性,并且如果不需要使用某些高级前端工具(Sass、webpack、npm…),则可能不需要它。

页面和模板包含 page-inclusion

接下来,让我们查看如何在AEM页面中引用clientlibs。 Web开发的常见最佳实践是在HTML标题中包含CSS <head> 和JavaScript,然后关闭 </body> 标记之前。

  1. 浏览到文章页面模板,网址为 http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page/structure.html

  2. 单击 页面信息 图标,然后在菜单中,选择 页面策略 以打开 页面策略 对话框。

    文章页面模板菜单页面策略

    “页面信息”>“页面策略”

  3. 请注意,的类别 wknd.dependencieswknd.site 此处列出。 默认情况下,通过页面策略配置的clientlibs会被拆分,以便在页面头中包含CSS,在正文末尾包含JavaScript。 您可以明确列出要在页头中加载的clientlib JavaScript。 这就是 wknd.dependencies.

    文章页面模板菜单页面策略

    note note
    NOTE
    也可以引用 wknd.sitewknd.dependencies 直接从页面组件使用 customheaderlibs.htmlcustomfooterlibs.html 脚本。 使用模板提供了灵活性,您可以在中选择每个模板使用的clientlib。 例如,如果您有一个重的JavaScript库,该库将只用在选定模板上。
  4. 导航至 洛杉矶滑板场 使用创建的页面 文章页面模板http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html.

  5. 单击 页面信息 图标,然后在菜单中,选择 查看已发布的项目 以在AEM编辑器外部打开文章页面。

    查看已发布的项目

  6. 查看页面源 http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled 并且您应该能够在以下位置看到以下clientlib引用: <head>

    code language-html
    <head>
    ...
    <script src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.js"></script>
    <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.css" type="text/css">
    <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-78fb9cea4c3a2cc17edce2c2b32631e2-lc.min.css" type="text/css">
    ...
    </head>
    

    请注意,clientlibs正在使用代理 /etc.clientlibs 端点。 您还应该看到以下clientlib包含在页面底部:

    code language-html
    ...
    <script src="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-7157cf8cb32ed66d50e4e49cdc50780a-lc.min.js"></script>
    <script src="/etc.clientlibs/wknd/clientlibs/clientlib-base.lc-53e6f96eb92561a1bdcc1cb196e9d9ca-lc.min.js"></script>
    ...
    </body>
    
    note note
    NOTE
    对于AEM 6.5/6.4,客户端库不会自动缩小。 请参阅有关以下内容的文档 HTML库管理器启用缩小(推荐).
    note warning
    WARNING
    在发布端,客户端库至关重要 提供自 /apps 因为出于安全原因,应使用 Dispatcher过滤器部分. 此 allowProxy属性 的客户端库来确保从提供CSS和JS /etc.clientlibs.

后续步骤 next-steps

了解如何使用Experience Manager的样式系统实施单个样式并重用核心组件。 用样式系统进行开发 涵盖使用样式系统通过模板编辑器的品牌特定CSS和高级策略配置来扩展核心组件。

查看完成的代码 GitHub 或在Git分支上本地查看和部署代码 tutorial/client-side-libraries-solution.

  1. 克隆 github.com/adobe/aem-wknd-guides 存储库。
  2. 查看 tutorial/client-side-libraries-solution 分支。

其他工具和资源 additional-resources

Webpack DevServer — 静态标记 webpack-dev-static

在前几个练习中, ui.frontend 模块已更新,并通过构建过程最终看到这些更改反映在AEM中。 接下来,让我们看一下使用 webpack-dev-server 快速开发前端样式, 静态 HTML。

如果大多数样式和前端代码由专用的前端开发人员执行,而这些开发人员可能无法轻松访问AEM环境,则这项技术将会非常实用。 这种技术还允许FED直接对HTML进行修改,然后可以将其移交给AEM开发人员作为组件实施。

  1. 复制LA滑板公园文章页面的页面源,位于 http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled.

  2. 重新打开IDE。 将复制的AEM标记粘贴到 index.htmlui.frontend 下的模块 src/main/webpack/static.

  3. 编辑复制的标记并移除对的所有引用 clientlib-siteclientlib-dependencies

    code language-html
    <!-- remove -->
    <script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.js"></script>
    <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.css" type="text/css">
    <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.css" type="text/css">
    ...
    <script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site.js"></script>
    

    删除这些引用,因为webpack开发服务器会自动生成这些工件。

  4. 从新终端启动webpack开发服务器,方法是从 ui.frontend 模块:

    code language-shell
    $ cd ~/code/aem-guides-wknd/ui.frontend/
    $ npm start
    
    > aem-maven-archetype@1.0.0 start code/aem-guides-wknd/ui.frontend
    > webpack-dev-server --open --config ./webpack.dev.js
    
  5. 此操作将在以下位置打开一个新的浏览器窗口: http://localhost:8080/ 静态标记。

  6. 编辑文件 src/main/webpack/site/_variables.scss 文件。 替换 $text-color 规则中指定了:

    code language-diff
    - $text-color:              $black;
    + $text-color:              $pink;
    

    保存更改。

  7. 您应该会在以下日期自动看到所做的更改在浏览器中自动反映出来: http://localhost:8080.

    本地webpack开发服务器更改

  8. 查看 /aem-guides-wknd.ui.frontend/webpack.dev.js 文件。 这包含用于启动webpack-dev-server的webpack配置。 它代理路径 /content/etc.clientlibs 在本地运行的AEM实例中进行调用。 这就是图像及其他clientlibs(不由 ui.frontend 代码)将变得可用。

    note caution
    CAUTION
    静态标记的图像src指向本地AEM实例上的活动图像组件。 如果图像的路径发生更改、AEM未启动或浏览器未登录到本地AEM实例,则图像会显示为已损坏。 如果移交给外部资源,也可以使用静态引用替换图像。
  9. 您可以 停止 从命令行键入webpack server CTRL+C.

已弃用 develop-aemfed

已弃用 是一个开源命令行工具,可用于加快前端开发。 它由 aemsyncBrowsersync、和 Sling日志跟踪程序.

从高层次上说, aemfed旨在监听 ui.apps 模块并将它们直接自动同步到正在运行的AEM实例。 本地浏览器会根据更改自动刷新,从而加快前端开发。 它还能够与Sling日志跟踪器配合使用,以在终端中直接自动显示任何服务器端错误。

如果您在 ui.apps 模块、修改HTL脚本和创建自定义组件, 已弃用 可以是一个功能强大的工具。 可在此处找到完整文档.

调试客户端库 debugging-clientlibs

使用不同的方法 类别嵌入 要包含多个客户端库,进行故障排除可能会比较麻烦。 AEM公开了多种工具来帮助解决此问题。 最重要的工具之一是 重建客户端库 它会强制AEM重新编译任何LESS文件并生成CSS。

  • 转储库 — 列出在AEM实例中注册的客户端库。 <host>/libs/granite/ui/content/dumplibs.html

  • 测试输出 — 允许用户根据类别查看clientlib include的预期HTML输出。 <host>/libs/granite/ui/content/dumplibs.test.html

  • 库依赖项验证 — 突出显示任何无法找到的依赖项或嵌入类别。 <host>/libs/granite/ui/content/dumplibs.validate.html

  • 重建客户端库 — 允许用户强制AEM重建客户端库或使客户端库的缓存失效。 在使用LESS进行开发时,此工具有效,因为这会强制AEM重新编译生成的CSS。 通常,使缓存失效然后执行页面刷新比重建库更有效。 <host>/libs/granite/ui/content/dumplibs.rebuild.html

重建客户端库

recommendation-more-help
b2a561c1-47c0-4182-b8c1-757a197484f9