Criação de formulários adaptáveis usando o esquema JSON creating-adaptive-forms-using-json-schema
O Adobe recomenda o uso da captura de dados moderna e extensível Componentes principaispara criação de um novo Forms adaptávelou adição de Forms adaptável às páginas do AEM Sites. Esses componentes representam um avanço significativo na criação do Forms adaptável, garantindo experiências de usuário impressionantes. Este artigo descreve a abordagem mais antiga para criar o Forms adaptável usando componentes de base.
Pré-requisitos prerequisites
A criação de um formulário adaptável usando um Esquema JSON como seu modelo de formulário requer compreensão básica do Esquema JSON. É recomendável ler o conteúdo a seguir antes deste artigo.
Utilização de um esquema JSON como modelo de formulário using-a-json-schema-as-form-model
Adobe Experience Manager Forms O oferece suporte à criação de um formulário adaptável usando um Esquema JSON existente como o modelo de formulário. Esse esquema JSON representa a estrutura em que os dados são produzidos ou consumidos pelo sistema de back-end em sua organização. O esquema JSON usado deve ser compatível com Especificações da v4.
Os principais recursos do uso de um Esquema JSON são:
- A estrutura do JSON é exibida como uma árvore na guia Localizador de conteúdo no modo de criação de um formulário adaptável. Você pode arrastar e adicionar elemento da hierarquia JSON ao formulário adaptável.
- Você pode preencher previamente o formulário usando o JSON compatível com o esquema associado.
- No envio, os dados inseridos pelo usuário são enviados como JSON, que se alinha ao esquema associado.
Um Esquema JSON consiste em tipos de elementos simples e complexos. Os elementos têm atributos que adicionam regras ao elemento. Quando esses elementos e atributos são arrastados para um formulário adaptável, eles são mapeados automaticamente para o componente de formulário adaptável correspondente.
Esse mapeamento de elementos JSON com componentes de formulário adaptáveis é o seguinte:
"birthDate": {
"type": "string",
"format": "date",
"pattern": "date{DD MMMM, YYYY}",
"aem:affKeyword": [
"DOB",
"Date of Birth"
],
"description": "Date of birth in DD MMMM, YYYY",
"aem:afProperties": {
"displayPictureClause": "date{DD MMMM, YYYY}",
"displayPatternType": "date{DD MMMM, YYYY}",
"validationPatternType": "date{DD MMMM, YYYY}",
"validatePictureClause": "date{DD MMMM, YYYY}",
"validatePictureClauseMessage": "Date must be in DD MMMM, YYYY format."
}
Propriedades comuns do esquema common-schema-properties
O Formulário adaptável usa as informações disponíveis no Esquema JSON para mapear cada campo gerado. Em especial:
- A variável
title
A propriedade serve como rótulo para os componentes de formulário adaptável. - A variável
description
é definida como descrição longa para um componente de formulário adaptável. - A variável
default
A propriedade serve como valor inicial de um campo de formulário adaptável. - A variável
maxLength
é definida comomaxlength
atributo do componente de campo de texto. - A variável
minimum
,maximum
,exclusiveMinimum
, eexclusiveMaximum
As propriedades são usadas para o componente Caixa numérica. - Para oferecer suporte ao intervalo de
DatePicker component
propriedades adicionais do Esquema JSONminDate
emaxDate
são fornecidos. - A variável
minItems
emaxItems
as propriedades são usadas para restringir o número de itens/campos que podem ser adicionados ou removidos de um componente do painel. - A variável
readOnly
propriedade define a variávelreadonly
atributo de um componente de formulário adaptável. - A variável
required
marca o campo de formulário adaptável como obrigatório, enquanto no painel (em que o tipo é objeto), os dados JSON enviados finais têm campos com valor vazio que correspondem a esse objeto. - A variável
pattern
é definida como o padrão de validação (expressão regular) no formulário adaptável. - A extensão do arquivo de Esquema JSON deve ser mantida em .schema.json. Por exemplo, <filename>.schema.json.
Exemplo de esquema JSON sample-json-schema
Este é um exemplo de um Esquema JSON.
{
"$schema": "https://json-schema.org/draft-04/schema#",
"definitions": {
"employee": {
"type": "object",
"properties": {
"userName": {
"type": "string"
},
"dateOfBirth": {
"type": "string",
"format": "date"
},
"email": {
"type": "string",
"format": "email"
},
"language": {
"type": "string"
},
"personalDetails": {
"$ref": "#/definitions/personalDetails"
},
"projectDetails": {
"$ref": "#/definitions/projectDetails"
}
},
"required": [
"userName",
"dateOfBirth",
"language"
]
},
"personalDetails": {
"type": "object",
"properties": {
"GeneralDetails": {
"$ref": "#/definitions/GeneralDetails"
},
"Family": {
"$ref": "#/definitions/Family"
},
"Income": {
"$ref": "#/definitions/Income"
}
}
},
"projectDetails": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"projects": {
"$ref": "#/definitions/projects"
}
}
},
"minItems": 1,
"maxItems": 4
},
"projects": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"projectsAdditional": {
"$ref": "#/definitions/projectsAdditional"
}
}
},
"minItems": 1,
"maxItems": 4
},
"projectsAdditional": {
"type": "array",
"items": {
"properties": {
"Additional_name": {
"type": "string"
},
"Additional_areacode": {
"type": "number"
}
}
},
"minItems": 1,
"maxItems": 4
},
"GeneralDetails": {
"type": "object",
"properties": {
"age": {
"type": "number"
},
"married": {
"type": "boolean"
},
"phone": {
"type": "number",
"aem:afProperties": {
"sling:resourceType": "/libs/fd/af/components/guidetelephone",
"guideNodeClass": "guideTelephone"
}
},
"address": {
"type": "string"
}
}
},
"Family": {
"type": "object",
"properties": {
"spouse": {
"$ref": "#/definitions/spouse"
},
"kids": {
"$ref": "#/definitions/kids"
}
}
},
"Income": {
"type": "object",
"properties": {
"monthly": {
"type": "number"
},
"yearly": {
"type": "number"
}
}
},
"spouse": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"Income": {
"$ref": "#/definitions/Income"
}
}
},
"kids": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
}
}
},
"minItems": 1,
"maxItems": 4
}
},
"type": "object",
"properties": {
"employee": {
"$ref": "#/definitions/employee"
}
}
}
Definições de esquema reutilizáveis reusable-schema-definitions
As chaves de definição são usadas para identificar esquemas reutilizáveis. As definições de esquema reutilizáveis são usadas para criar fragmentos. É semelhante à identificação de tipos complexos em XSD. Um exemplo de Esquema JSON com definições é fornecido abaixo:
{
"$schema": "https://json-schema.org/draft-04/schema#",
"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" }
},
"required": ["street_address", "city", "state"]
}
},
"type": "object",
"properties": {
"billing_address": { "$ref": "#/definitions/address" },
"shipping_address": { "$ref": "#/definitions/address" }
}
}
O exemplo acima define um registro de cliente, em que cada cliente tem um endereço de entrega e de cobrança. A estrutura de ambos os endereços é a mesma — os endereços têm endereço, cidade e estado — portanto, é uma boa ideia não duplicar os endereços. Também facilita a adição e a exclusão de campos para qualquer alteração futura.
Pré-configuração de campos na definição do esquema JSON pre-configuring-fields-in-json-schema-definition
Você pode usar o aem:afProperties propriedade para pré-configurar o campo Esquema JSON para mapear para um componente de formulário adaptável personalizado. Um exemplo está listado abaixo:
{
"properties": {
"sizeInMB": {
"type": "integer",
"minimum": 16,
"maximum": 512,
"aem:afProperties" : {
"sling:resourceType" : "/apps/fd/af/components/guideTextBox",
"guideNodeClass" : "guideTextBox"
}
}
},
"required": [ "sizeInMB" ],
"additionalProperties": false
}
Configurar scripts ou expressões para objetos de formulário configure-scripts-or-expressions-for-form-objects
JavaScript é a linguagem de expressão de formulários adaptáveis. Todas as expressões são expressões JavaScript válidas e usam APIs de modelo de script de formulários adaptáveis. Você pode pré-configurar objetos de formulário para avaliar uma expressão em um evento de formulário.
Use a propriedade aem:afproperties para pré-configurar expressões de formulário adaptáveis ou scripts para componentes de formulário adaptáveis. Por exemplo, quando o evento de inicialização é acionado, o código abaixo define o valor do campo de telefone e imprime um valor no log:
"telephone": {
"type": "string",
"pattern": "/\\d{10}/",
"aem:affKeyword": ["phone", "telephone","mobile phone", "work phone", "home phone", "telephone number", "telephone no", "phone number"],
"description": "Telephone Number",
"aem:afProperties" : {
"sling:resourceType" : "fd/af/components/guidetelephone",
"guideNodeClass" : "guideTelephone",
"events": {
"Initialize" : "this.value = \"1234567890\"; console.log(\"ef:gh\") "
}
}
}
Você deve ser um membro do grupo forms-power-user para configurar scripts ou expressões para objeto de formulário. A tabela abaixo lista todos os eventos de script compatíveis com um componente de formulário adaptável.
Alguns exemplos de uso de eventos em um JSON estão ocultando um campo em inicializar evento e configurando o valor de outro campo em evento de confirmação de valor. Para obter informações detalhadas sobre a criação de expressões para os eventos de script, consulte Expressões de formulário adaptável.
Este é o exemplo de código JSON para exemplos mencionados anteriormente.
Ocultar um campo no evento de inicialização hiding-a-field-on-initialize-event
"name": {
"type": "string",
"aem:afProperties": {
"events" : {
"Initialize" : "this.visible = false;"
}
}
}
Configurar o valor de outro campo no evento de confirmação de valor configure-value-of-another-field-on-value-commit-event
"Income": {
"type": "object",
"properties": {
"monthly": {
"type": "number",
"aem:afProperties": {
"events" : {
"Value Commit" : "IncomeYearly.value = this.value * 12;"
}
}
},
"yearly": {
"type": "number",
"aem:afProperties": {
"name": "IncomeYearly"
}
}
}
}
Limitar valores aceitáveis para um componente de formulário adaptável limit-acceptable-values-for-an-adaptive-form-component
Você pode adicionar as seguintes restrições aos elementos do Esquema JSON para limitar os valores aceitáveis para um componente de formulário adaptável:
Ativar dados compatíveis com o esquema enablig-schema-compliant-data
Para permitir que todo o Forms adaptável baseado em esquema JSON gere dados compatíveis com o esquema no envio do formulário, siga estas etapas:
- Acesse o console da Web do Experience Manager em
https://server:host/system/console/configMgr
. - Localizar Configuração do canal da Web de comunicação adaptável e interativa.
- Selecione para abrir a configuração no modo de edição.
- Selecione o Gerar dados compatíveis com o esquema caixa de seleção
- Salve as configurações.
Construções não suportadas non-supported-constructs
Os formulários adaptáveis não são compatíveis com as seguintes construções de Esquema JSON:
- Tipo nulo
- Tipos de união, como qualquer um, e
- OneOf, AnyOf, AllOf e NOT
- Somente matrizes homogêneas são compatíveis. Portanto, a restrição de itens deve ser um objeto e não uma matriz.
Perguntas frequentes frequently-asked-questions
Por que não consigo arrastar elementos individuais de um subformulário (estrutura gerada de qualquer tipo complexo) para subformulários repetíveis (os valores minOccours ou maxOccurs são maiores que 1)?
Em um subformulário repetível, você deve usar o subformulário completo. Se desejar apenas campos seletivos, use a estrutura inteira e exclua os indesejados.
Tenho uma estrutura complexa longa no Localizador de conteúdo. Como posso encontrar um elemento específico?
Você tem duas opções:
- Rolar pela estrutura de árvore
- Use a caixa Pesquisar para localizar um elemento
Qual deve ser a extensão do arquivo de esquema JSON?
A extensão do arquivo de esquema JSON deve ser .schema.json. Por exemplo, <filename>.schema.json.