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

Pré-requisitos

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

Uso de um Schema JSON como modelo de formulário

Adobe Experience Manager Forms suporta a criação de um formulário adaptável usando um Schema JSON existente como modelo de formulário. Este Schema JSON representa a estrutura na qual os dados são produzidos ou consumidos pelo sistema de back-end em sua organização. O Schema JSON que você usa deve ser compatível com especificações v4.

Os principais recursos do uso de um Schema 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 schema associado.
  • No envio, os dados inseridos pelo usuário são enviados como JSON que se alinha ao schema associado.

Um Schema 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, 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.

{

"type" : "string",

}



Campo de texto


propriedade number
Campo numérico com subtipo definido como float
propriedade integer
Campo numérico com subtipo definido como integer
propriedade booleana
Alternar
propriedade object
Painel
propriedade array Painel repetível com min e max iguais a minItems e maxItems respectivamente. Somente matrizes homogêneas são suportadas. Portanto, a restrição de itens deve ser um objeto e não uma matriz.

Propriedades de schemas comuns

O Formulário adaptável usa as informações disponíveis no Schema 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 uma 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 é 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érico.
  • Para oferecer suporte ao intervalo para DatePicker component propriedades adicionais do Schema JSON minDate e maxDate são fornecidas.
  • 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 (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 normal) na forma adaptável.
  • A extensão do arquivo de Schema JSON deve ser mantida .schema.json. Por exemplo, <nome_do_arquivo>.schema.json.

Schema JSON de exemplo

Aqui está um exemplo de um Schema 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 schemas reutilizáveis

As chaves de definição são usadas para identificar schemas reutilizáveis. As definições de schema reutilizáveis são usadas para criar fragmentos. É semelhante a identificar tipos complexos no XSD. Um exemplo de Schema 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, 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 duplicado 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 em Definição de Schema JSON

Você pode usar a propriedade aem:afProperties para pré-configurar o campo de Schema 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

JavaScript é a linguagem 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. É possível 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 initialize é acionado, o código abaixo define o valor do campo phone 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 form-power-user group para configurar scripts ou expressões para objetos de formulário. A tabela abaixo lista todos os eventos de script suportados para um componente de formulário adaptável.

Componente \ Evento initialize
Calcular Visibilidade Validar Ativado Confirmação de valor Clique em Opções
Campo de texto
Campo numérico
Escalonador Numérico
Botão de opção
Telefone
Alternar
Botão
Caixa de seleção
Suspenso
Opção de Imagem
Campo de Entrada de Data
Seletor de datas
E-mail
Anexo de arquivo
Imagem
Draw
Painel

Alguns exemplos de uso de eventos em um JSON estão ocultando um campo no evento initialize e configurando o valor de outro campo no evento commit value. Para obter informações detalhadas sobre como criar expressões para os eventos de script, consulte Expressões de formulário adaptáveis.

Este é o exemplo de código JSON para exemplos mencionados anteriormente.

Ocultar um campo no evento initialize

"name": {
    "type": "string",
    "aem:afProperties": {
        "events" : {
            "Initialize" : "this.visible = false;"
        }
    }
}

Configurar o valor de outro campo no evento de confirmação de valor

"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

É possível adicionar as seguintes restrições aos elementos do Schema JSON para limitar os valores aceitáveis para um componente de formulário adaptável:

propriedade schema

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 schema 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 adaptativos não suportam as seguintes construções de Schema JSON:

  • Tipo nulo
  • tipos de uniões, como qualquer, e
  • OneOf, AnyOf, AllOf e NOT
  • Somente matrizes homogêneas são suportadas. Portanto, a restrição de itens deve ser um objeto e não uma matriz.

Perguntas frequentes

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 você quiser 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

Qual deve ser a extensão do arquivo de schema JSON?

A extensão do arquivo de Schema JSON deve ser .schema.json. Por exemplo, <nome_do_arquivo>.schema.json.

Nesta página

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free