Criar aparências personalizadas para campos de formulário adaptáveis create-custom-appearances-for-adaptive-form-fields
Introdução introduction
Os formulários adaptáveis usam o estrutura de aparência para ajudá-lo a criar aparências personalizadas para campos de formulário adaptáveis e fornecer uma experiência de usuário diferente. Por exemplo, substitua botões de opção e caixas de seleção por botões de alternância ou use plug-ins jQuery personalizados para restringir as entradas de usuários em campos como números de telefone ou ID de email.
Este documento explica como usar um plug-in jQuery para criar essas experiências alternativas para campos de formulário adaptáveis. Além disso, mostra um exemplo para criar uma aparência personalizada para que o componente de campo numérico apareça como um passo ou controle deslizante numérico.
Vamos primeiro analisar os termos e conceitos principais usados neste artigo.
Aparência Refere-se ao estilo, aparência e comportamento e à organização de vários elementos de um campo de formulário adaptável. Geralmente inclui um rótulo, uma área interativa para fornecer entradas, um ícone de ajuda e descrições curtas e longas do campo. A personalização da aparência discutida neste artigo é aplicável para a aparência da área de entrada do campo.
Plug-in do jQuery Fornece um mecanismo padrão, baseado na estrutura do widget jQuery, para implementar uma aparência alternativa.
ClientLib Um sistema de bibliotecas do lado do cliente em AEM processamento no lado do cliente, orientado por códigos complexos de JavaScript e CSS. Para obter mais informações, consulte Usar bibliotecas do lado do cliente.
Arquétipo Um kit de ferramentas de modelo de projeto Maven definido como um padrão ou modelo original para projetos Maven. Para obter mais informações, consulte Introdução aos arquétipos.
Controle do usuário Refere-se ao elemento principal em um widget que contém o valor do campo e é usado pela estrutura de aparência para vincular a interface do usuário de widget personalizada ao modelo de formulário adaptável.
Etapas para criar uma aparência personalizada steps-to-create-a-custom-appearance
As etapas, em um alto nível, para criar uma aparência personalizada são as seguintes:
-
Criar um projeto: Crie um projeto Maven que gera um pacote de conteúdo para implantar no AEM.
-
Estender uma classe de widget existente: Estender uma classe de widget existente e substituir as classes necessárias.
-
Criar uma biblioteca do cliente: Crie um
clientLib: af.customwidget
e adicione os arquivos JavaScript e CSS necessários. -
Criar e instalar o projeto: Crie o projeto Maven e instale o pacote de conteúdo gerado no AEM.
-
Atualizar o formulário adaptável: Atualize as propriedades dos campos de formulário adaptáveis para usar a aparência personalizada.
Criar um projeto create-a-project
Um arquétipo maven é um ponto de partida para a criação de uma aparência personalizada. Os detalhes do arquétipo a ser usado são os seguintes:
- Repositório: https://repo.adobe.com/nexus/content/groups/public/
- Id Do Artefato: custom-appearance-archetype
- ID do Grupo: com.adobe.aemforms
- Versão: 1.0.4
Execute o seguinte comando para criar um projeto local com base no arquétipo:
mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
O comando baixa os plug-ins e as informações do arquétipo do Maven do repositório e gera um projeto com base nas seguintes informações:
- groupId: ID de grupo usada pelo projeto Maven gerado
- artifactId: ID de artefato usada pelo projeto Maven gerado.
- version: Versão do projeto Maven gerado.
- pacote: Pacote usado para a estrutura do arquivo.
- artifactName: Nome do artefato do pacote de AEM gerado.
- packageGroup: Grupo de pacotes do pacote de AEM gerado.
- widgetName: Nome de aparência usado para referência.
O projeto gerado tem a seguinte estrutura:
─<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
Estender uma classe de widget existente extend-an-existing-widget-class
Depois que o modelo do projeto for criado, faça as seguintes alterações, conforme necessário:
-
Inclua a dependência de plug-in de terceiros no projeto.
- Coloque os plug-ins jQuery de terceiros ou personalizados no
jqueryplugin/javascript
pasta e arquivos CSS relacionados najqueryplugin/css
pasta. Para obter mais detalhes, consulte os arquivos JS e CSS na seçãojqueryplugin/javascript and jqueryplugin/css
pasta. - Modifique o
js.txt
ecss.txt
arquivos para incluir qualquer arquivo JavaScript e CSS adicional do plug-in jQuery.
- Coloque os plug-ins jQuery de terceiros ou personalizados no
-
Integre o plug-in de terceiros à estrutura para permitir a interação entre a estrutura de aparência personalizada e o plug-in jQuery. O novo widget será funcional somente após estender ou substituir as seguintes funções.
-
Atualize o arquivo JavaScript no
integration/javascript
, conforme necessário.- Substituir o texto
__widgetName__
com o nome real do widget. - Estenda o widget a partir de uma classe de widget pronta para uso adequada. Na maioria dos casos, é a classe de widget correspondente ao widget existente que está sendo substituído. O nome da classe pai é usado em vários locais, portanto, é recomendável procurar por todas as instâncias da cadeia de caracteres
xfaWidget.textField
no arquivo e substitua-os pela classe pai real usada. - Estender o
render
para fornecer uma interface alternativa. É o local de onde o plug-in jQuery será chamado para atualizar a interface do usuário ou o comportamento de interação. Orender
deve retornar um elemento de controle de usuário. - Estender o
getOptionsMap
para substituir qualquer configuração de opção afetada devido a uma alteração no widget. A função retorna um mapeamento que fornece detalhes para a ação ser executada na alteração de uma opção. As chaves são as opções fornecidas para o widget e os valores são as funções chamadas sempre que uma alteração na opção é detectada. - O
getEventMap
O método mapeia eventos acionados pelo widget, com os eventos exigidos pelo modelo de formulário adaptável. O valor padrão mapeia eventos HTML padrão para o widget padrão e precisa ser atualizado se um evento alternativo for acionado. - O
showDisplayValue
eshowValue
aplique a cláusula de exibição e edição de imagem e pode ser substituída para ter um comportamento alternativo. - O
getCommitValue
é chamado pela estrutura de formulários adaptáveis quando a variávelcommit
ocorre. Geralmente, é o evento exit, exceto para os elementos suspensos, de botão de opção e de caixa de seleção, onde ocorre durante a mudança). Para obter mais informações, consulte Expressões adaptáveis do Forms. - O arquivo de modelo fornece a implementação de exemplo para vários métodos. Remova os métodos que não devem ser estendidos.
- Substituir o texto
Criar uma biblioteca do cliente create-a-client-library
O projeto de amostra gerado pelo arquétipo Maven cria automaticamente as bibliotecas de clientes necessárias e as envolve em uma biblioteca de clientes com uma categoria af.customwidgets
. Os arquivos JavaScript e CSS disponíveis no af.customwidgets
são incluídas automaticamente no tempo de execução.
Criar e instalar build-and-install
Para criar o projeto, execute o seguinte comando no shell para gerar um pacote CRX que precise ser instalado no servidor AEM.
mvn clean install
settings.xml
arquivo.Atualizar o formulário adaptável update-the-adaptive-form
Para aplicar a aparência personalizada a um campo de formulário adaptável:
- Abra o formulário adaptável no modo de edição.
- Abra o Propriedade para o campo no qual você deseja aplicar a aparência personalizada.
- No Estilo , atualize a guia
CSS class
para adicionar o nome da aparência nawidget_<widgetName>
formato. Por exemplo: widget_numericstep
Exemplo: Criar uma aparência personalizada sample-create-a-custom-appearance-nbsp
Agora vamos observar um exemplo para criar uma aparência personalizada para que um campo numérico apareça como um passo ou controle deslizante numérico. Execute as seguintes etapas:
-
Execute o seguinte comando para criar um projeto local com base no arquétipo 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
Ele solicita que você especifique valores para os seguintes parâmetros.
Os valores usados nessa amostra são realçados em negrito.
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
-
Navegue até o
customWidgets
(valor especificado para a variávelartifactID
e execute o seguinte comando para gerar um projeto Eclipse:mvn eclipse:eclipse
-
Abra a ferramenta Eclipse e faça o seguinte para importar o projeto Eclipse:
-
Selecionar Arquivo > Importar > Projetos existentes no Workspace.
-
Procure e selecione a pasta onde você executou o
archetype:generate
comando. -
Clique em Concluir.
-
-
Selecione o widget a ser usado para a aparência personalizada. Este exemplo usa o seguinte widget de etapa numérica:
https://www.jqueryscript.net/form/User-Friendly-Number-Input-Spinner-with-jQuery-Bootstrap.html
No projeto do Eclipse, revise o código do plug-in no
plugin.js
para garantir que corresponda aos requisitos para a aparência. Nesta amostra, a aparência cumpre os seguintes requisitos:- O passo numérico deve se estender de
- $.xfaWidget.numericInput
. - O
set value
O método do widget define o valor após o foco estar no campo. É um requisito obrigatório para um widget de formulário adaptável. - O
render
deve ser substituído para chamar o métodobootstrapNumber
método . - Não há dependência adicional para o plug-in que não seja o código-fonte principal do plug-in.
- A amostra não executa nenhum estilo na etapa, portanto, nenhum CSS adicional é necessário.
- O
$userControl
deve estar disponível para a variávelrender
método . É um campo da variáveltext
tipo que é clonado com o código do plug-in. - O + e - botões devem ser desativados quando o campo estiver desativado.
- O passo numérico deve se estender de
-
Substitua o conteúdo da variável
bootstrap-number-input.js
(plugin jQuery) com o conteúdo donumericStepper-plugin.js
arquivo. -
No
numericStepper-widget.js
, adicione o seguinte código para substituir o método de renderização para chamar o plug-in e retornar o$userControl
objeto:code language-java 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; }
-
No
numericStepper-widget.js
, substitua ogetOptionsMap
para substituir a opção de acesso e ocultar os botões + e - no modo desativado.code language-java 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; }
-
Salve as alterações, navegue até a pasta que contém a variável
pom.xml
e execute o seguinte comando Maven para criar o projeto:mvn clean install
-
Instale o pacote usando o Gerenciador de pacotes AEM.
-
Abra o formulário adaptável no modo de edição no qual deseja aplicar a aparência personalizada e faça o seguinte:
-
Clique com o botão direito do mouse no campo no qual deseja aplicar a aparência e clique em Editar para abrir a caixa de diálogo Editar componente .
-
Na guia Estilo , atualize o Classe CSS propriedade a ser adicionada
widget_numericStepper
.
-
A nova aparência que você acabou de criar está disponível para uso.