Criação de formulários adaptáveis usando o esquema JSON creating-adaptive-forms-using-json-schema
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 seguinte conteúdo antes deste artigo.
Uso de um esquema JSON como modelo de formulário using-a-json-schema-as-form-model
O AEM Forms suporta a 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 na qual os dados são produzidos ou consumidos pelo sistema de back-end na organização. O Esquema JSON que você usa deve ser compatível com especificações 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.
- É possível preencher previamente o formulário usando JSON compatível com o schema associado.
- Ao enviar, os dados inseridos pelo usuário são enviados como JSON que se alinha ao schema 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:
Propriedades comuns do schema 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 propriedade title serve como rótulo para os componentes de formulário adaptáveis.
- A propriedade description é definida como descrição longa para um componente de formulário adaptável.
- A propriedade padrão serve como valor inicial de um campo de formulário adaptável.
- A propriedade maxLength é definida como atributo maxlength do componente de campo de texto.
- As propriedades mínima, máxima, exclusivaMinimum e exclusivaMaximum são usadas para o componente Caixa numérica .
- Para oferecer suporte ao intervalo do componente DatePicker, são fornecidas propriedades adicionais do Esquema JSON minDate e maxDate.
- As propriedades minItems e maxItems são usadas para restringir o número de itens/campos que podem ser adicionados ou removidos de um componente de painel.
- A propriedade readOnly define o atributo somente leitura de um componente de formulário adaptável.
- A propriedade necessária marca o campo do formulário adaptável como obrigatório, enquanto no caso de painel (onde o tipo é objeto), os dados JSON enviados finais têm campos com valor vazio correspondente a esse objeto.
- A propriedade pattern é definida como o padrão de validação (expressão regular) em forma adaptável.
- A extensão do arquivo Esquema JSON deve ser mantida .schema.json. Por exemplo, <filename>.schema.json.
Exemplo de esquema JSON sample-json-schema
Aqui está 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 a identificar tipos complexos no 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 envio e de faturamento. A estrutura de ambos os endereços é a mesma — os endereços têm um endereço de rua, cidade e estado — portanto, é uma boa ideia não duplicar os endereços. Também facilita a adição e 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 é 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
}
Limite 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:
Construções não suportadas non-supported-constructs
Os formulários adaptáveis não são compatíveis com as seguintes construções do Esquema JSON:
- Tipo nulo
- Tipos de União como qualquer, e
- OneOf, AnyOf, AllOf e NOT
- Somente arrays homogêneos 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, é necessário usar o subformulário completo. Se quiser apenas campos seletivos, use toda a estrutura e exclua os não desejados.
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