Création de formulaires adaptatifs à l’aide d’un schéma JSON creating-adaptive-forms-using-json-schema

CAUTION
AEM 6.4 a atteint la fin de la prise en charge étendue et cette documentation n’est plus mise à jour. Pour plus d’informations, voir notre période de support technique. Rechercher les versions prises en charge here.

Prérequis prerequisites

La création d’un formulaire adaptatif à l’aide d’un schéma JSON en tant que modèle de formulaire nécessite une compréhension de base du schéma JSON. Il est recommandé de lire le contenu suivant avant cet article.

Utilisation d’un schéma JSON comme modèle de formulaire using-a-json-schema-as-form-model

AEM Forms prend en charge la création d’un formulaire adaptatif en utilisant un schéma JSON existant comme modèle de formulaire. Ce schéma JSON représente la structure dans laquelle les données sont générées ou utilisées par le système back-end de votre organisation. Le schéma JSON que vous utilisez doit être compatible avec les spécifications v4.

Les principales fonctionnalités de l’utilisation d’un schéma JSON sont les suivantes :

  • La structure du modèle JSON s’affiche sous forme d’arborescence sous l’onglet Outil de recherche de contenu en mode création pour un formulaire adaptatif. Vous pouvez faire glisser et ajouter un élément de la hiérarchie JSON au formulaire adaptatif.
  • Vous pouvez préremplir le formulaire à l’aide de JSON conforme au schéma associé.
  • Lors de l’envoi, les données saisies par l’utilisateur sont envoyées au format JSON en phase avec le schéma associé.

Un schéma JSON se compose de types d’éléments simples et complexes. Les éléments possèdent des attributs qui ajoutent des règles à ceux-ci. Lorsque ces éléments et attributs sont déplacés sur un formulaire adaptatif, ils sont automatiquement mappés au composant de formulaire adaptatif correspondant.

Ce mappage des éléments JSON avec les composants de formulaire adaptatif est le suivant :

Élément, propriétés ou attributs JSON
Composant de formulaire adaptatif

Propriétés de chaînes avec contrainte d’énumération et enumNames.

Syntaxe,

{

"type" : "string",

"enum" : ["M", "F"]

"enumNames" : ["Male", "Female"]

}

Composant Liste déroulante :

  • Les valeurs répertoriées dans enumNames s’affichent dans la zone de dépôt.
  • Les valeurs répertoriées dans l’énumération sont utilisées pour le calcul.

Propriété de chaîne avec contrainte de format. Par exemple, courrier électronique et date.

Syntaxe,

{

"type" : "string",

"format" : "email"

}

  • Le composant Email est mappé lorsque le type est chaîne et le format est email.
  • Le composant de zone de texte avec validation est mappé lorsque le type est chaîne et le format est nom d’hôte.

{

"type" : "string",

}

Champ de texte
propriété number
Champ numérique dont le sous-type est défini pour flotter
propriété integer
Champ numérique dont le sous-type est défini sur entier
propriété boolean
Basculer
propriété object
Panneau
Propriété du tableau
Panneau répétable dont le minimum et le maximum sont respectivement égaux à minItems et maxItems. Seuls les tableaux homogènes sont pris en charge. Par conséquent, la contrainte d’éléments doit être un objet et n’est pas un tableau.

Propriétés communes de schéma common-schema-properties

Le formulaire adaptatif utilise les informations disponibles dans le schéma JSON pour mapper chaque champ généré. En particulier :

  • La propriété title sert de libellé pour les composants de formulaire adaptatif.
  • La propriété description est définie comme description longue pour un composant de formulaire adaptatif.
  • La propriété par défaut sert de valeur initiale d’un champ de formulaire adaptatif.
  • La propriété maxLength est définie en tant qu’attribut maxlength du composant de champ de texte.
  • Les propriétés minimum, maximum, exclusiveMinimum et exclusiveMaximum sont utilisées pour le composant de zone numérique.
  • Pour prendre en charge la plage pour le composant DatePicker, d’autres propriétés de schéma JSON minDate et maxDate sont fournies.
  • Les propriétés minItems et maxItems permettent de limiter le nombre d’éléments/de champs pouvant être ajoutés ou supprimés d’un composant de panneau.
  • La propriété readOnly définit l’attribut readonly d’un composant de formulaire adaptatif.
  • La propriété requise marque le champ de formulaire adaptatif comme étant obligatoire, tandis que dans le cas du panneau (où le type est objet), les données JSON finales envoyées ont des champs avec une valeur vide correspondant à cet objet.
  • La propriété pattern est définie comme modèle de validation (expression régulière) dans le formulaire adaptatif.
  • L’extension du fichier de schéma JSON doit être conservée dans .schema.json. Par exemple, <nom_fichier>.schema.json.

Exemple de schéma JSON sample-json-schema

Voici un exemple de schéma 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"
  }
 }
}

Définitions de schéma réutilisables reusable-schema-definitions

Les clés de définition sont utilisées pour identifier les schémas réutilisables. Les définitions de schéma réutilisables sont utilisées pour créer des fragments. Elle est similaire à l’identification des types complexes dans XSD. Un exemple de schéma JSON dont la définition est fournie ci-dessous :

{
  "$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" }
  }
}

L’exemple ci-dessus définit un enregistrement de client, où chaque client possède à la fois une adresse de livraison et une adresse de facturation. La structure des deux adresses est la même (les adresses ont une adresse de rue, une ville et un état), il est donc préférable de ne pas dupliquer les adresses. Cela facilite également l’ajout et la suppression de champs pour toute modification ultérieure.

Préconfiguration des champs dans la définition du schéma JSON pre-configuring-fields-in-json-schema-definition

Vous pouvez utiliser la propriété aem:afProperties pour préconfigurer le champ de schéma JSON pour mapper vers un composant de formulaire adaptatif personnalisé. Un exemple est répertorié ci-dessous :

{
    "properties": {
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512,
            "aem:afProperties" : {
                 "sling:resourceType" : "/apps/fd/af/components/guideTextBox",
                 "guideNodeClass" : "guideTextBox"
             }
        }
    },
    "required": [ "sizeInMB" ],
    "additionalProperties": false
}

Valeurs possibles de limite pour un composant de formulaire adaptatif limit-acceptable-values-for-an-adaptive-form-component

Vous pouvez ajouter les restrictions suivantes aux éléments de schéma JSON pour limiter les valeurs possibles pour un composant de formulaire adaptatif :

Propriété de schéma
Type de données
Description
Composant
maximum
Chaîne
Spécifie la limite supérieure pour les valeurs numériques et les dates. Par défaut, la valeur maximale est incluse.
  • Zone numérique
  • Procédure pas à pas numérique
  • Sélecteur de date
minimum
Chaîne
Indique la limite inférieure pour les valeurs numériques et les dates. Par défaut, la valeur minimale est incluse.
  • Zone numérique
  • Procédure pas à pas numérique
  • Sélecteur de date
exclusiveMaximum
Booléen

Si la valeur est true, la valeur numérique ou la date spécifiée dans le composant du formulaire doit être inférieure à la valeur numérique ou la date spécifiée pour la propriété maximum.

Si la valeur est false, la valeur numérique ou la date spécifiée dans le composant du formulaire doit être inférieure ou égale à la valeur numérique ou à la date spécifiée pour la propriété maximum.

  • Zone numérique
  • Procédure pas à pas numérique
  • Sélecteur de date
exclusiveMinimum
Booléen

Si la valeur est true, la valeur numérique ou la date spécifiée dans le composant du formulaire doit être supérieure à la valeur numérique ou à la date spécifiée pour la propriété minimum.

Si la valeur est false, la valeur numérique ou la date spécifiée dans le composant du formulaire doit être supérieure ou égale à la valeur numérique ou à la date spécifiée pour la propriété minimale.

  • Zone numérique
  • Procédure pas à pas numérique
  • Sélecteur de date
minLength
Chaîne
Indique le nombre minimum de caractères autorisés dans un composant. La longueur minimale doit être égale ou supérieure à zéro.
  • Zone de texte
maxLength
Chaîne
Indique le nombre maximal de caractères autorisés dans un composant. La longueur maximale doit être égale ou supérieure à zéro.
  • Zone de texte
pattern
Chaîne

Indique la séquence des caractères. Un composant accepte les caractères si les caractères sont conformes au modèle spécifié.

La propriété pattern correspond au modèle de validation du composant de formulaire adaptatif correspondant.

  • Tous les composants de formulaires adaptatifs qui sont mappés vers un schéma XSD
maxItems
Chaîne
Indique le nombre maximal d’éléments dans un tableau. Le nombre maximal d’éléments doit être égal ou supérieur à zéro.
minItems
Chaîne
Indique le nombre minimum d’éléments dans un tableau. Le nombre d’éléments minimum doit être égal ou supérieur à zéro.

Éléments non pris en charge non-supported-constructs

Les formulaires adaptatifs ne prennent pas en charge les éléments de schéma JSON suivants :

  • Type null
  • Types d’unions, tels que les types appropriés, et
  • OneOf, AnyOf, AllOf et NOT
  • Seuls les tableaux homogènes sont pris en charge. Par conséquent, la contrainte d’éléments doit être un objet et non un tableau.

Questions fréquemment posées frequently-asked-questions

Pourquoi est-ce que je ne parviens pas à faire glisser des éléments individuels d’un sous-formulaire (structure générée à partir de n’importe quel type complexe) pour les sous-formulaires répétables (les valeurs minOccurs ou maxOccurs sont supérieures à 1) ?

Dans un sous-formulaire répétable, vous devez utiliser le sous-formulaire complet. Si vous souhaitez uniquement des champs sélectifs, utilisez la structure entière et supprimez les champs indésirables.

J’ai une longue structure complexe dans l’outil de recherche de contenu. Comment puis-je trouver un élément spécifique ?

Vous disposez de deux options :

  • Parcourez la structure de l’arborescence.
  • Utilisez la zone Rechercher pour rechercher un élément.
recommendation-more-help
a6ebf046-2b8b-4543-bd46-42a0d77792da