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

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:

Criado para:

Iniciante
Intermediário
Usuário
Desenvolvedor

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

Campo numérico

Escalonador numérico

Botão de opção

Telefone

Interruptor

Botão

Caixa de seleção

Suspenso

Opção de imagem

Campo de entrada de data

Seletor de data

Anexo de arquivo

Imagem

Draw

Painel

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:

Vá para o Experience Manager web console em https://server:host/system/console/configMgr.
Localize Configuração de Canal da Web de Comunicação entre Interações e Formulários Adaptáveis.
Selecione para abrir a configuração no modo de edição.
Marque a caixa de seleção Gerar dados compatíveis com o esquema.
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