Criar aparências personalizadas para campos de formulário adaptáveis
Introdução
Formulários adaptáveis aproveitam a estrutura de aparência para ajudá-lo a criar aparências personalizadas para campos de formulário adaptáveis e fornecer uma experiência diferente ao usuário. 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 do jQuery para criar essas experiências alternativas para campos de formulário adaptáveis. Além disso, exibe um exemplo para criar uma aparência personalizada para que o componente de campo numérico apareça como um auxiliar numérico ou um controle deslizante.
Vamos primeiro ver 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 à aparência da área de entrada do campo.
Plug-in 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 do lado do cliente controlado por complexos códigos JavaScript e CSS. Para obter mais informações, consulte Usar bibliotecas do lado do cliente.
Archetype 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árioRefere-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 do widget personalizado ao modelo de formulário adaptável.
Etapas para criar uma aparência personalizada
As etapas, em 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 implantação no AEM.
Estende uma classe de widget existente: Estende uma classe de widget existente e substitui as classes necessárias.
Criar uma biblioteca de clientes: Crie uma clientLib: af.customwidget biblioteca e adicione os arquivos JavaScript e CSS necessários.
Crie e instale o projeto: Crie o projeto Maven e instale o pacote de conteúdo gerado no AEM.
Atualize o formulário adaptável: Atualize as propriedades de campos de formulário adaptáveis para usar a aparência personalizada.
Criar um projeto
Um arquétipo maven é um ponto de partida para a criação de uma aparência personalizada. Os detalhes do arquétipo a utilizar são os seguintes:
O comando baixa os plug-ins Maven e as informações de tipo de arquivo do repositório e gera um projeto com base nas seguintes informações:
groupId: ID do grupo usada pelo projeto Maven gerado
artefatoId: ID de artefato usada pelo projeto Maven gerado.
versão: Versão do projeto Maven gerado.
pacote: Pacote usado para a estrutura do arquivo.
artefatoName: 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
Depois que o modelo de projeto for criado, faça as seguintes alterações, conforme necessário:
Inclua a dependência do plug-in de terceiros no projeto.
Coloque os plug-ins jQuery personalizados ou de terceiros na jqueryplugin/javascript pasta e os arquivos CSS relacionados na jqueryplugin/css pasta. Para obter mais detalhes, consulte os arquivos JS e CSS na jqueryplugin/javascript and jqueryplugin/css pasta.
Modifique os arquivos js.txt e css.txt para incluir qualquer arquivo adicional JavaScript e CSS do plug-in jQuery.
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 estará funcional somente depois que você estender ou substituir as seguintes funções.
Função
Descrição
render
A função de renderização retorna o objeto jQuery para o elemento HTML padrão do widget. O elemento HTML padrão deve ser do tipo focalizável. Por exemplo, <a>, <input>e <li>. O elemento retornado é usado como $userControl. Se a restrição $userControl especificar acima, as funções da AbstractWidget classe funcionarão conforme esperado, caso contrário, algumas das APIs comuns (foco, clique) exigirão alterações.
getEventMap
Retorna um mapa para converter eventos HTML em eventos XFA. {
blur: XFA_EXIT_EVENT,
} Este exemplo mostra que blur é um evento HTML e XFA_EXIT_EVENT é o evento XFA correspondente.
getOptionsMap
Retorna um mapa que fornece detalhes sobre a ação a ser executada na alteração de uma opção. As teclas são as opções fornecidas para o widget e os valores são funções que são chamadas sempre que uma alteração na opção é detectada. O widget fornece manipuladores para todas as opções comuns (exceto value e displayValue).
getCommitValue
A estrutura do widget jQuery carrega a função sempre que o valor do widget jQuery é salvo no modelo XFA (por exemplo, no evento exit de um campo de texto). A implementação deve retornar o valor salvo no widget. O manipulador é fornecido com o novo valor para a opção.
showValue
Por padrão, no XFA ao inserir o evento, o campo rawValue é exibido. Essa função é chamada para mostrar o rawValue ao usuário.
showDisplayValue
Por padrão, no XFA ao sair do evento, o campo formattedValue é exibido. Essa função é chamada para mostrar o formattedValue ao usuário.
Atualize o arquivo JavaScript na integration/javascript pasta, conforme necessário.
Substitua o texto __widgetName__ pelo nome do widget real.
Estenda o widget de uma classe de widget pronta para uso adequada. Na maioria dos casos, é a classe do widget correspondente ao widget existente que está sendo substituído. O nome da classe pai é usado em vários locais, portanto, é recomendável procurar todas as instâncias da string xfaWidget.textField no arquivo e substituí-las pela classe pai real usada.
Estenda o render método 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. O render método deve retornar um elemento de controle de usuário.
Estende o getOptionsMap método 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 quando uma opção é alterada. As teclas são as opções fornecidas ao widget e os valores são as funções chamadas sempre que uma alteração na opção é detectada.
O getEventMap 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.
A cláusula de exibição showDisplayValue e edição de imagem é aplicada showValue e pode ser substituída para ter um comportamento alternativo.
O getCommitValue método é chamado pela estrutura de formulários adaptáveis quando o commitevento ocorre. Geralmente, é o evento exit, exceto para os elementos suspensos, botões de opção e caixas de seleção nos quais ocorre ao mudar). Para obter mais informações, consulte Forms Expressão adaptável.
O arquivo de modelo fornece implementação de amostra para vários métodos. Remova os métodos que não devem ser estendidos.
Criar uma biblioteca de cliente
O projeto de amostra gerado pelo arquétipo Maven cria automaticamente as bibliotecas do cliente necessárias e as envolve em uma biblioteca do cliente com uma categoria af.customwidgets. Os arquivos JavaScript e CSS disponíveis no af.customwidgets são incluídos automaticamente no tempo de execução.
Criar e instalar
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
Observação
O projeto maven se refere a um repositório remoto dentro do arquivo POM. Isso é feito apenas para fins de referência e, de acordo com os padrões Maven, as informações do repositório são capturadas no settings.xml arquivo.
Atualizar o formulário adaptável
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 a caixa de diálogo Propriedade do campo no qual você deseja aplicar a aparência personalizada.
Na guia Estilo , atualize a CSS class propriedade para adicionar o nome da aparência no widget_<widgetName> formato. Por exemplo: widget_numericstep
Amostra: Criar uma aparência personalizada
Agora vamos observar um exemplo para criar uma aparência personalizada para que um campo numérico apareça como uma revisão numérica ou um controle deslizante. Execute as seguintes etapas:
Execute o seguinte comando para criar um projeto local com base no arquétipo Maven:
No projeto do Eclipse, reveja o código do plug-in no plugin.js arquivo para garantir que ele corresponda aos requisitos para a aparência. Nessa amostra, a aparência atende aos seguintes requisitos:
O passo numérico deve se estender de - $.xfaWidget.numericInput.
O set value 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 método precisa ser substituído para chamar o bootstrapNumber método.
Não há nenhuma 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 revisão, portanto, nenhum CSS adicional é necessário.
O $userControl objeto deve estar disponível para o render método. É um campo do text tipo clonado com o código do plug-in.
Os botões + e - devem ser desativados quando o campo estiver desativado.
Substitua o conteúdo do bootstrap-number-input.js (plug-in jQuery) pelo conteúdo do numericStepper-plugin.js arquivo.
No numericStepper-widget.js arquivo, adicione o seguinte código para substituir o método de renderização para chamar o plug-in e retornar o $userControl objeto:
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 arquivo, substitua a getOptionsMap propriedade para substituir a opção de acesso e oculte os botões + e - no modo desativado.
