Show Menu
主题×

为自适应表单域创建自定义外观

简介

自适应表单利用外 观框架 ,帮助您为自适应表单字段创建自定义外观并提供不同的用户体验。 例如,将单选按钮和复选框替换为切换按钮或使用自定义jQuery插件限制用户在电话号码或电子邮件ID等字段中的输入。
本文档介绍如何使用jQuery插件为自适应表单字段创建这些替代体验。 此外,它还展示了一个示例,用于为数字字段组件创建自定义外观以显示为数字步进器或滑块。
我们首先来看一下本文使用的关键术语和概念。
外观 -指自适应表单字段中各个元素的样式、外观和组织。 它通常包括标签、提供输入的交互区域、帮助图标以及字段的简短和长描述。 本文讨论的外观定制适用于字段输入区域的外观。
jQuery plugin 提供基于jQuery构件框架的标准机制,以实现替代外观。
ClientLib 由复杂JavaScript和CSS代码驱动的AEM客户端处理中的客户端库系统。 有关详细信息,请参阅使用客户端库。
Archetype A Maven项目模板工具包定义为Maven项目的原始图案或模型。 有关详细信息,请参阅原型简介。
用户控制 -指构件中包含字段值的主元素,外观框架用于将自定义构件UI与自适应表单模型绑定。

创建自定义外观的步骤

创建自定义外观的高级步骤如下:
  1. 创建项目 :创建一个Maven项目,该项目生成要在AEM上部署的内容包。
  2. 扩展现有构件类 :扩展现有构件类并覆盖所需的类。
  3. 创建客户端库 :创建库 clientLib: af.customwidget 并添加所需的JavaScript和CSS文件。
  4. 构建和安装项目 :构建Maven项目并在AEM上安装生成的内容包。
  5. 更新自适应表单 :更新自适应表单字段属性以使用自定义外观。

创建项目

主原型是创建自定义外观的起点。 要使用的原型的详细信息如下:
  • 存储库 :https://repo.adobe.com/nexus/content/groups/public/
  • 伪像Id :custom-appearance-archetype
  • 组ID :com.adobe.aemforms
  • 版本 :1.0.4
执行以下命令以基于原型创建本地项目:
mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
该命令从存储库下载Maven插件和原型信息,并基于以下信息生成项目:
  • groupId :由生成的Maven项目使用的组ID
  • artifactId :由生成的Maven项目使用的对象ID。
  • 版本 :生成的Maven项目的版本。
  • :用于文件结构的包。
  • artifactName :生成的AEM包的对象名称。
  • packageGroup :生成的AEM包的包组。
  • widgetName :用于引用的外观名称。
生成的项目具有以下结构:
─<artifactId>

 └───src

     └───main

         └───content

             └───jcr_root

                 └───etc

                     └───clientlibs

                         └───custom

                             └───<widgetName>

                                 ├───common [client library - af.customwidgets which encapsulates below clientLibs]

                                 ├───integration [client library - af.customwidgets.<widgetName>_widget which contains template files for integrating a third-party plugin with Adaptive Forms]

                                 │   ├───css

                                 │   └───javascript

                                 └───jqueryplugin [client library - af.customwidgets.<widgetName>_plugin which holds the third-party plugins and related dependencies]

                                     ├───css

                                     └───javascript

扩展现有构件类

创建项目模板后,请根据需要执行以下更改:
  1. 将第三方插件依赖关系包含到项目。
    1. 将第三方或自定义jQuery插件放在文件夹中, jqueryplugin/javascript 并将相关的CSS文件放在文件 jqueryplugin/css 夹中。 有关详细信息,请参阅文件夹下的JS和CSS jqueryplugin/javascript and jqueryplugin/css 文件。
    2. 修改和 js.txt 文件以 css.txt 包括jQuery插件的任何其他JavaScript和CSS文件。
  2. 将第三方插件与框架集成,以实现自定义外观框架与jQuery插件之间的交互。 只有在您扩展或覆盖以下功能后,新构件才能正常工作。
函数 描述
render 渲染函数返回构件的默认HTML元素的jQuery对象。 默认的HTML元素应为可聚焦类型。 例如, <a> <input> <li> 。 返回的元素将用作 $userControl 。 如果指 $userControl 定了上述约束,则类的函数将按预期工 AbstractWidget 作,否则一些常见API(焦点、单击)需要更改。
getEventMap 返回将HTML事件转换为XFA事件的映射。 此 { blur: XFA_EXIT_EVENT, } 示例说明 blur 是HTML事件, XFA_EXIT_EVENT 是相应的XFA事件。
getOptionsMap 返回一个地图,其中提供有关在选项更改时要执行的操作的详细信息。 键是提供给构件的选项,值是检测到选项更改时调用的函数。 构件为所有常用选项(除和之外)提供 value 了处 displayValue 理函数。
getCommitValue 每当jQuery Widget的值保存在XFA模型中(例如,在文本字段的退出事件中)时,jQuery Widget框架将加载该函数。 实施应返回在构件中保存的值。 该处理函数提供了选项的新值。
showValue 默认情况下,在XFA中,进入事件时, rawValue 将显示字段的名称。 调用此函数向用户 rawValue 显示。
showDisplayValue 默认情况下,在XFA退出事件中, formattedValue 显示字段的名称。 调用此函数向用户 formattedValue 显示。
  1. 根据需要更新文件夹 integration/javascript 中的JavaScript文件。
    • 将文本替 __widgetName__ 换为实际构件名称。
    • 从合适的现成构件类扩展构件。 在大多数情况下,它是与要替换的现有构件相对应的构件类。 父类名称用于多个位置,因此建议在文件中搜索该字符串的所有实例,并将其替换为使用的实际父类。 xfaWidget.textField
    • 扩展方 render 法以提供替代UI。 它是从中调用jQuery插件以更新UI或交互行为的位置。 该方 render 法应返回用户控制元素。
    • 扩展方 getOptionsMap 法以覆盖因构件更改而受影响的任何选项设置。 该函数返回一个映射,该映射提供了选项更改时要执行的操作的详细信息。 键是提供给构件的选项,值是检测到选项更改时调用的函数。
    • 该方 getEventMap 法将构件触发的事件与自适应表单模型所需的事件进行映射。 默认值映射默认构件的标准HTML事件,如果触发了替代事件,则需要更新该事件。
    • 并应 showDisplayValue 用显 showValue 示和编辑图片子句,可以被覆盖以具有替代行为。
    • 当事 getCommitValue 件发生时,自适应表单框架将调用 commit 该方法。 通常,它是退出事件,但下拉列表、单选按钮和复选框元素除外,它们在更改时发生)。 有关详细信息,请参阅自 适应表单表达式
    • 模板文件为各种方法提供了示例实现。 删除不要扩展的方法。

创建客户端库

由Maven原型生成的示例项目会自动创建所需的客户端库,并将它们包装到包含类别的客户端库中 af.customwidgets 。 运行时会自动包含中可用的JavaScript af.customwidgets 和CSS文件。

构建和安装

要构建项目,请在shell上执行以下命令,以生成需要安装在AEM服务器上的CRX包。
mvn clean install
主项目引用POM文件中的远程存储库。 这仅供参考,根据Maven标准,存储库信息将在文件中捕 settings.xml 获。

更新自适应表单

要将自定义外观应用于自适应表单字段,请执行以下操作:
  1. 在编辑模式下打开自适应表单。
  2. 打开 要应用自定义外观的字段的“属性 ”对话框。
  3. 在“样 ”选项卡中,更新属 CSS class 性以添加格式的外观名 widget_<widgetName> 称。 例如: widget_numericstepper

示例:创建自定义外观

现在,让我们看一个示例,为数字字段创建自定义外观以显示为数字步进器或滑块。 执行以下步骤:
  1. 执行以下命令以创建基于Maven原型的本地项目:
    mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
    它提示您为以下参数指定值。 此示例中使用的值以粗体突出显示
    Define value for property 'groupId': com.adobe.afwidgets
    Define value for property 'artifactId': customWidgets
    Define value for property 'version': 1.0.1-SNAPSHOT
    Define value for property 'package': com.adobe.afwidgets
    Define value for property 'artifactName': customWidgets
    Define value for property 'packageGroup': adobe/customWidgets
    Define value for property 'widgetName': numericStepper
  2. 导航到 customWidgets (属性的指定值)目 artifactID 录并执行以下命令以生成Eclipse项目:
    mvn eclipse:eclipse
  3. 打开Eclipse工具并执行以下操作以导入Eclipse项目:
    1. 选择“ 文件”>“导入”>“现有项目到工作区”
    2. 浏览并选择执行命令的文件 archetype:generate 夹。
    3. 单击“ 完成 ”。
  4. 选择要用于自定义外观的构件。 此范例使用以下数字步进构件:
    在Eclipse项目中,查看文件中的插件代 plugin.js 码,确保它符合外观要求。 在此示例中,外观满足以下要求:
    • 数字步进器应从扩展 - $.xfaWidget.numericInput
    • 构件 set value 的方法在焦点位于字段后设置值。 这是自适应表单构件的必需要求。
    • 需要 render 覆盖该方法才能调用该 bootstrapNumber 方法。
    • 除了插件的主源代码之外,该插件没有其他依赖关系。
    • 该范例不对步进器执行任何样式,因此不需要任何其他CSS。
    • $userControl 对象应可用于该方 render 法。 它是使用插件 text 代码克隆的类型字段。
    • 用字段 时,应禁用+和——按钮。
  5. 将(jQuery插件) bootstrap-number-input.js 的内容替换为文件的内 numericStepper-plugin.js 容。
  6. 在文件 numericStepper-widget.js 中,添加以下代码以覆盖渲染方法以调用插件并返回对 $userControl 象:
    render : function() {
         var control = $.xfaWidget.numericInput.prototype.render.apply(this, arguments);
         var $control = $(control);
         var controlObject;
         try{
             if($control){
             $control.bootstrapNumber();
             var id = $control.attr("id");
             controlObject = $("#"+id);
             }
         }catch (exc){
              console.log(exc);
         }
         return controlObject;
    }
    
    
  7. 在文件 numericStepper-widget.js 中,覆盖属性以覆 getOptionsMap 盖访问选项,并在禁用模式下隐藏+和——按钮。
    getOptionsMap: function(){
        var parentOptionsMap = $.xfaWidget.numericInput.prototype.getOptionsMap.apply(this,arguments),
    
        newMap = $.extend({},parentOptionsMap,
    
         {
    
               "access": function(val) {
               switch(val) {
                  case "open" :
                    this.$userControl.removeAttr("readOnly");
                    this.$userControl.removeAttr("aria-readonly");
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
                  case "nonInteractive" :
                  case "protected" :
                    this.$userControl.attr("disabled", "disabled");
                    this.$userControl.attr("aria-disabled", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                 case "readOnly" :
                    this.$userControl.attr("readOnly", "readOnly");
                    this.$userControl.attr("aria-readonly", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                default :
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
              }
           },
       });
       return newMap;
     }
    
    
  8. 保存更改,导览至包含该文件的文 pom.xml 件夹,然后执行以下Maven命令以构建项目:
    mvn clean install
  9. 使用AEM包管理器安装包。
  10. 在要应用自定义外观的编辑模式下打开自适应表单,然后执行以下操作:
    1. 右键单击要应用外观的字段,然后单击“编辑 ,打开“编辑组件”对话框。
    2. 在“样式”选项卡中,更新 要添加的CSS类 属性 widget_numericStepper
您刚刚创建的新外观现在可供使用。