Criação de formulários adaptáveis usando o esquema JSON creating-adaptive-forms-using-json-schema

O Adobe recomenda o uso de Componentes principaisde captura de dados moderna e extensível para criar um novo Forms Adaptávelou adicionar o 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.

Versão
Link do artigo
AEM as a Cloud Service
Clique aqui
AEM 6.5
Este artigo

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 dá 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 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."
              }
Elemento JSON, propriedades ou atributos
Componente de formulário adaptável

Propriedades de string com 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 cálculo.

Propriedade de cadeia de caracteres 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 Caixa de texto com validação é mapeado quando o tipo é string e o formato é hostname.

{

"type" : "string",

}

Campo de texto
propriedade numérica
Campo numérico com subtipo definido como flutuante
propriedade inteira
Campo Numérico com subtipo definido como inteiro
propriedade booleana
Alternar
propriedade de objeto
Painel
propriedade de matriz
Painel repetível com mín. e máx. iguais a minItems e maxItems, respectivamente. Somente matrizes homogêneas são compatíveis. Portanto, a restrição de itens deve ser um objeto e não uma matriz.

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 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 default serve como valor inicial de um campo de formulário adaptável.
  • A propriedade maxLength está definida como atributo maxlength do componente de campo de texto.
  • As propriedades minimum, maximum, exclusiveMinimum e exclusiveMaximum são usadas para o componente de Caixa Numérica.
  • Para dar suporte ao intervalo de DatePicker component, são fornecidas as 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 do painel.
  • A propriedade readOnly define o atributo readonly de um componente de formulário adaptável.
  • A propriedade 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 propriedade pattern é definida como o padrão de validação (expressão regular) no formato adaptável.
  • A extensão do arquivo de Esquema JSON deve ser mantida em .schema.json. Por exemplo, <nome do arquivo>.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 a propriedade aem:afProperties para pré-configurar o campo de 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

O JavaScript é o idioma de expressão dos 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 membro do grupo de formulários-usuário para configurar scripts ou expressões para o objeto de formulário. A tabela abaixo lista todos os eventos de script compatíveis com um componente de formulário adaptável.

Componente \ Evento
inicializar
Calcular
Visibilidade
Validar
Habilitado
Confirmação de valor
Clique em
Opções
Campo de texto
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Campo numérico
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Escalonador numérico
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Botão de opção
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Telefone
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Interruptor
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Botão
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Caixa de seleção
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Suspenso
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Opção de imagem
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Campo de entrada de data
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Seletor de data
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Email
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Anexo de arquivo
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Imagem
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Draw
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim
Painel
Ícone de marca de verificação Sim
Ícone de marca de verificação Sim

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 como criar expressões para 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:

Propriedade do esquema
Tipo de dados
Descrição
Componente
maximum
String
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 data
minimum
String
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 data
exclusiveMaximum
Booleano

Se true, o valor numérico ou a data especificada no componente do formulário deverá ser menor que o valor numérico ou a data especificada para a propriedade máxima.

Se false, 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 maximum.

  • Caixa numérica
  • Escalonador numérico
  • Seletor de data
exclusiveMinimum
Booleano

Se true, o valor numérico ou a data especificada no componente do formulário deverá ser maior que o valor numérico ou a data especificada para a propriedade minimum.

Se false, 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 minimum.

  • Caixa numérica
  • Escalonador numérico
  • Seletor de data
minLength
String
Especifica o número mínimo de caracteres permitidos em um componente. O comprimento mínimo deve ser igual ou maior que zero.
  • Caixa de texto
maxLength
String
Especifica o número máximo de caracteres permitidos em um componente. O comprimento máximo deve ser igual ou maior que zero.
  • Caixa de texto
pattern
String

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 mapeados para um esquema XSD
maxItems
String
Especifica o número máximo de itens em uma matriz. O máximo de itens deve ser igual ou maior que zero.
minItems
String
Especifica o número mínimo de itens em uma matriz. Os itens mínimos devem ser iguais ou maiores que zero.

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:

  1. Vá para o Experience Manager web console em https://server:host/system/console/configMgr.
  2. Localize Configuração de Canal da Web de Comunicação entre Interações e Formulários Adaptáveis.
  3. Selecione para abrir a configuração no modo de edição.
  4. Marque a caixa de seleção Gerar dados compatíveis com o esquema.
  5. Salve as configurações.

configuração do canal da Web de formulário adaptável e comunicação interativa

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 (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, <nome do arquivo>.schema.json.

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2