Show Menu
TÓPICOS×

Criação de formulários adaptáveis usando o Esquema JSON

Pré-requisitos

A criação de um formulário adaptável usando um Esquema JSON como seu modelo de formulário requer o entendimento básico do Esquema JSON. É recomendável ler o seguinte conteúdo antes deste artigo.

Uso de um Esquema JSON como modelo de formulário

O AEM Forms suporta a criação de um formulário adaptável usando um Esquema JSON existente como modelo de formulário. Este Esquema JSON representa a estrutura na qual os dados são produzidos ou consumidos pelo sistema de back-end em sua organização. O Esquema JSON que você usa deve estar em conformidade com as especificações schemav4.
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 elementos da hierarquia JSON ao formulário adaptável.
  • É possível pré-preencher o formulário usando 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:
Elemento, propriedades ou atributos JSON Componente de formulário adaptável
Propriedades de string com as restrições enum e enumNames.
Sintaxe,
{
"type" : "string",
"enum" : ["M", "F"]
"enumNames" : ["Male", "Female"]
}
Componente suspenso:
  • Os valores listados em enumNames são exibidos na caixa suspensa.
  • Os valores listados na enumeração são usados para o cálculo.
Propriedade String com restrição de formato. Por exemplo, email e data.
Sintaxe,
{
"type" : "string",
"format" : "email"
}
  • O componente de email é mapeado quando o tipo é string e o formato é email.
  • O componente da caixa de texto com validação é mapeado quando o tipo é string e o formato é nome do host.
{
"Tipo": "string",
}
Campo de texto
propriedade number Campo numérico com subtipo definido como flutuante
propriedade integer Campo numérico com subtipo definido como inteiro
propriedade booleana Alternar
object property Painel
propriedade array Painel repetível com min e max iguais a minItems e maxItems respectivamente. Somente arrays homogêneos são suportados. Portanto, a restrição de itens deve ser um objeto e não uma matriz.

Propriedades de esquema comuns

O Formulário adaptável usa as informações disponíveis no Esquema JSON para mapear cada campo gerado. Nomeadamente:
  • 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 de caixa Numérico.
  • Para suportar o 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 readonly de um componente de formulário adaptável.
  • A propriedade necessária marca o campo de formulário adaptável como obrigatório, enquanto no caso de panel (onde type é object), 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) na forma adaptável.
  • A extensão do arquivo JSON Schema deve ser mantida .schema.json. Por exemplo, <filename>.schema.json.

Exemplo de esquema JSON

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

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. Uma amostra de Esquema JSON com definições é apresentada 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, no qual 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 - então é uma boa ideia não duplicar os endereços. Além disso, facilita a adição e exclusão de campos para qualquer alteração futura.

Pré-configuração de campos na Definição de Esquema JSON

Você pode usar a propriedade aem:afProperties 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
}

Valores limite aceitáveis para um componente de formulário adaptável

É possível adicionar as seguintes restrições aos elementos do Esquema JSON para limitar os valores aceitáveis para um componente de formulário adaptável:
Propriedade do esquema
Tipo de dados
Descrição
Componente
maximum
Sequência de caracteres
Especifica o limite superior para valores numéricos e datas. Por padrão, o valor máximo é incluído.
  • Caixa numérica
  • Escalonador Numérico
  • Seletor de datas
minimum
Sequência de caracteres
Especifica o limite inferior para valores numéricos e datas. Por padrão, o valor mínimo é incluído.
  • Caixa numérica
  • Escalonador Numérico
  • Seletor de datas
exclusiveMaximum
Booleano
Se verdadeiro, o valor numérico ou a data especificada no componente do formulário deve ser menor que o valor numérico ou a data especificada para a propriedade máxima.
Se falso, o valor numérico ou a data especificada no componente do formulário deve ser menor ou igual ao valor numérico ou à data especificada para a propriedade máxima.
  • Caixa numérica
  • Escalonador Numérico
  • Seletor de datas
exclusiveMinimum
Booleano
Se verdadeiro, o valor numérico ou a data especificada no componente do formulário deve ser maior que o valor numérico ou a data especificada para a propriedade mínima.
Se falso, o valor numérico ou a data especificada no componente do formulário deve ser maior ou igual ao valor numérico ou à data especificada para a propriedade mínima.
  • Caixa numérica
  • Escalonador Numérico
  • Seletor de datas
minLength
Sequência de caracteres
Especifica o número mínimo de caracteres permitidos em um componente. O comprimento mínimo deve ser igual ou superior a zero.
  • Caixa de texto
maxLength Sequência de caracteres Especifica o número máximo de caracteres permitidos em um componente. O comprimento máximo deve ser igual ou superior a zero.
  • Caixa de texto
pattern
Sequência de caracteres
Especifica a sequência dos caracteres. Um componente aceita os caracteres se eles estiverem em conformidade com o padrão especificado.
A propriedade pattern mapeia para o padrão de validação do componente de formulário adaptável correspondente.
  • Todos os componentes de formulários adaptáveis que estão mapeados para um esquema XSD
maxItems Sequência de caracteres Especifica o número máximo de itens em uma matriz. Os itens máximos devem ser iguais ou superiores a zero.
minItems Sequência de caracteres Especifica o número mínimo de itens em uma matriz. Os itens mínimos devem ser iguais ou superiores a zero.

Construção sem suporte

Os formulários adaptáveis não suportam as seguintes construções do Esquema JSON:
  • Tipo nulo
  • Tipos de União, tais como quaisquer, e
  • OneOf, AnyOf, AllOf e NOT
  • Somente arrays homogêneos são suportados. Portanto, a restrição de itens deve ser um objeto e não uma matriz.

Frequently asked questions

Por que não consigo arrastar elementos individuais de um subformulário (estrutura gerada a partir de qualquer tipo complexo) para subformulários repetitivos (os valores minOccours ou maxOccurs são maiores que 1)?
Em um subformulário repetível, é necessário usar o subformulário completo. Se desejar apenas campos seletivos, use a estrutura inteira e exclua os não desejados.
Tenho uma estrutura longa e complexa no Localizador de conteúdo. Como posso encontrar um elemento específico?
Você tem duas opções:
  • Percorrer a estrutura em árvore
  • Use a caixa Pesquisar para localizar um elemento