Show Menu
主题×

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

简介

自适应表单利用 外观框架 ,帮助您为自适应表单域创建自定义外观并提供不同的用户体验。 例如,将单选按钮和复选框替换为切换按钮或使用自定义jQuery插件限制用户在电话号码或电子邮件ID等字段中的输入。
此文档介绍如何使用jQuery插件为自适应表单字段创建这些替代体验。 此外,它还展示了一个示例,用于为数字字段组件创建自定义外观以显示为数字步进器或滑块。
我们首先来看一下本文使用的关键术语和概念。
外观 -指自适应表单字段各个元素的样式、外观和组织。 它通常包括标签、提供输入的交互区域、帮助图标以及字段的简短和长篇描述。 本文讨论的外观定制适用于字段输入区域的外观。
jQuery插件 提供基于jQuery构件框架的标准机制以实现替代外观。
ClientLib 由复杂的JavaScript和CSS代码驱动的AEM客户端处理中的客户端库系统。 有关详细信息,请参阅使用客户端库。
原型 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 : 自定外观原型
  • 组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构件的值保存在XFA模型中(例如文本字段的退出事件),jQuery构件框架就会加载该函数。 实施应返回在构件中保存的值。 该处理函数提供了选项的新值。
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 。 运行时自动包含中可 af.customwidgets 用的JavaScript和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
您刚刚创建的新外观现可供使用。