DocumentazioneAEM as a Cloud ServiceGuida utente

Progettazione di uno schema JSON per un modulo adattivo creating-adaptive-forms-using-json-schema

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

Creato per:

  • Principiante
  • Intermedio
  • Utente
  • Sviluppatore
Versione
Collegamento articolo
Componenti core
Fai clic qui
Foundation
Questo articolo

Adobe consiglia di utilizzare l'acquisizione dati moderna ed estensibile Componenti coreper la creazione di un nuovo Forms adattivoo l'aggiunta di Forms adattivo alle pagine AEM Sites. Questi componenti rappresentano un progresso significativo nella creazione di Forms adattivi, garantendo esperienze utente straordinarie. Questo articolo descrive un approccio precedente all’authoring di Forms adattivi utilizzando i componenti di base.

Versione
Collegamento articolo
AEM 6.5
Fai clic qui
AEM as a Cloud Service
Questo articolo

Prerequisiti prerequisites

Per creare un modulo adattivo utilizzando uno schema JSON come modello di modulo è necessario conoscere a fondo lo schema JSON. Si consiglia di leggere attentamente il seguente contenuto prima di questo articolo.

Utilizzo di uno schema JSON come modello di modulo using-a-json-schema-as-form-model

I moduli Adobe Experience Manager supportano la creazione di un modulo adattivo utilizzando uno schema JSON esistente come modello di modulo. Questo schema JSON rappresenta la struttura in cui i dati vengono prodotti o utilizzati dal sistema back-end dell’organizzazione. Lo schema JSON utilizzato deve essere conforme alle specifiche v4.

Le funzioni chiave dell’utilizzo di uno schema JSON sono:

  • La struttura del JSON viene visualizzata come struttura nella scheda Content Finder nella modalità di authoring di un modulo adattivo. Puoi trascinare e aggiungere un elemento dalla gerarchia JSON al modulo adattivo.
  • Puoi precompilare il modulo utilizzando un JSON conforme allo schema associato.
  • All’invio, i dati immessi dall’utente vengono inviati come JSON, in linea con lo schema associato.
  • Puoi anche creare il modulo in base allo schema JSON secondo le specifiche della versione 2012-2020.

Uno schema JSON è costituito da tipi di elementi semplici e complessi. Gli elementi dispongono di attributi che aggiungono regole all’elemento. Quando questi elementi e attributi vengono trascinati in un modulo adattivo, vengono mappati automaticamente al corrispondente componente Modulo adattivo.

La mappatura degli elementi JSON con i componenti del modulo adattivo è la seguente:

"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, proprietà o attributi
Componente modulo adattivo

Proprietà stringa con vincolo enum ed enumNames.

Sintassi,

{

"type" : "string",

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

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

}

Componente a discesa:

  • I valori elencati in enumNames vengono visualizzati nella casella di riepilogo.
  • I valori elencati nell'enum vengono utilizzati per il calcolo.

Proprietà stringa con vincolo di formato. Ad esempio e-mail e data.

Sintassi,

{

"type" : "string",

"format" : "email"

}

  • Il componente E-mail viene mappato quando il tipo è stringa e il formato è e-mail.
  • Il componente Textbox con convalida viene mappato quando il tipo è string (stringa) e il formato è hostname (nome host).

{

"type" : "string",

}

Campo di testo
proprietà numero
Campo numerico con sottotipo impostato su float
proprietà integer
Campo numerico con sottotipo impostato su integer
proprietà booleana
Cambia
proprietà oggetto
Pannello
proprietà array
Pannello ripetibile con min e max uguali rispettivamente a minItems e maxItems. Sono supportati solo array omogenei. Pertanto, il vincolo items deve essere un oggetto e non un array.

Proprietà comuni dello schema common-schema-properties

Il modulo adattivo utilizza le informazioni disponibili nello schema JSON per mappare ogni campo generato. In particolare:

  • La proprietà title funge da etichetta per i componenti Modulo adattivo.
  • La proprietà description viene impostata come descrizione lunga per un componente Modulo adattivo.
  • La proprietà default funge da valore iniziale di un campo Modulo adattivo.
  • La proprietà maxLength è impostata come attributo maxlength del componente del campo di testo.
  • Le proprietà minimum, maximum, exclusiveMinimum e exclusiveMaximum sono utilizzate per il componente casella numerica.
  • Per supportare l'intervallo per DatePicker component sono fornite proprietà aggiuntive dello schema JSON minDate e maxDate.
  • Le proprietà minItems e maxItems vengono utilizzate per limitare il numero di elementi/campi che possono essere aggiunti o rimossi da un componente del pannello.
  • La proprietà readOnly imposta l'attributo readonly di un componente Modulo adattivo.
  • La proprietà required contrassegna il campo Modulo adattivo come obbligatorio, mentre in panel (dove tipo è oggetto), i dati JSON inviati finali contengono campi con valore vuoto corrispondente a tale oggetto.
  • La proprietà pattern è impostata come pattern di convalida (espressione regolare) in Adaptive Form.
  • L’estensione del file di schema JSON deve essere mantenuta .schema.json. Ad esempio, <nomefile>.schema.json.

Schema JSON di esempio sample-json-schema

Schema JSON v4
code language-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"
}
}
}
Schema JSON 2012-20
code language-json 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/employee.schema.json",
  "$defs": {
    "employee": {
      "type": "object",
      "properties": {
        "userName": {
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "format": "date"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "language": {
          "type": "string"
        },
        "personalDetails": {
          "$ref": "#/$defs/personalDetails"
        },
        "projectDetails": {
          "$ref": "#/$defs/projectDetails"
        }
      },
      "required": [
        "userName",
        "dateOfBirth",
        "language"
      ]
    },
    "personalDetails": {
      "type": "object",
      "properties": {
        "GeneralDetails": {
          "$ref": "#/$defs/GeneralDetails"
        },
        "Family": {
          "$ref": "#/$defs/Family"
        },
        "Income": {
          "$ref": "#/$defs/Income"
        }
      }
    },
    "projectDetails": {
      "type": "array",
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "projects": {
            "$ref": "#/$defs/projects"
          }
        }
      },
      "minItems": 1,
      "maxItems": 4
    },
    "projects": {
      "type": "array",
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "projectsAdditional": {
            "$ref": "#/$defs/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"
        }
      }
      }
  }
  }

Le modifiche principali dallo schema JSON V4 alla versione 2020-12 sono le seguenti:

  • ID dichiarato come $id
  • definizioni dichiarate come $defs

Definizioni di schema riutilizzabili reusable-schema-definitions

Le chiavi di definizione vengono utilizzate per identificare gli schemi riutilizzabili. Per creare frammenti vengono utilizzate le definizioni di schema riutilizzabili. Di seguito è riportato un esempio di schema JSON con definizioni:

{
  "$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'esempio precedente definisce un record cliente, in cui ogni cliente ha sia un indirizzo di spedizione che un indirizzo di fatturazione. La struttura di entrambi gli indirizzi è la stessa: gli indirizzi hanno un indirizzo stradale, una città e uno stato, quindi è consigliabile non duplicare gli indirizzi. Inoltre, agevola l’aggiunta e l’eliminazione dei campi per eventuali modifiche future.

Preconfigurazione dei campi nella definizione dello schema JSON pre-configuring-fields-in-json-schema-definition

È possibile utilizzare la proprietà aem:afProperties per preconfigurare il campo Schema JSON da mappare a un componente modulo adattivo personalizzato. Di seguito è riportato un esempio:

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

Limitare valori accettabili per un componente Modulo adattivo limit-acceptable-values-for-an-adaptive-form-component

Per limitare i valori accettabili per un componente Modulo adattivo, puoi aggiungere le seguenti restrizioni agli elementi dello schema JSON:

Proprietà schema
Tipo di dati
Descrizione
Componente
maximum
Stringa
Specifica il limite superiore per valori numerici e date. Per impostazione predefinita, il valore massimo è incluso.
  • Casella numerica
  • Stepper numerico
  • Selettore data
minimum
Stringa
Specifica il limite inferiore per i valori numerici e le date. Per impostazione predefinita, è incluso il valore minimo.
  • Casella numerica
  • Stepper numerico
  • Selettore data
exclusiveMaximum
Booleano

Se true, il valore numerico o la data specificati nel componente del modulo devono essere inferiori al valore numerico o alla data specificati per la proprietà maximum.

Se false, il valore numerico o la data specificati nel componente del modulo deve essere minore o uguale al valore numerico o alla data specificati per la proprietà maximum.

  • Casella numerica
  • Stepper numerico
  • Selettore data
exclusiveMinimum
Booleano

Se true, il valore numerico o la data specificati nel componente del modulo devono essere maggiori del valore numerico o della data specificati per la proprietà minimum.

Se false, il valore numerico o la data specificati nel componente del modulo devono essere maggiori o uguali al valore numerico o alla data specificati per la proprietà minimum.

  • Casella numerica
  • Stepper numerico
  • Selettore data
minLength
Stringa
Specifica il numero minimo di caratteri consentito in un componente. La lunghezza minima deve essere uguale o maggiore di zero.
  • Casella di testo
maxLength
Stringa
Specifica il numero massimo di caratteri consentiti in un componente. La lunghezza massima deve essere uguale o maggiore di zero.
  • Casella di testo
pattern
Stringa

Specifica la sequenza dei caratteri. Un componente accetta i caratteri se questi sono conformi al modello specificato.

La proprietà pattern viene mappata sul pattern di convalida del componente Modulo adattivo corrispondente.

  • Tutti i componenti Forms adattivi mappati su uno schema XSD
maxItems
Stringa
Specifica il numero massimo di elementi in un array. Il numero massimo di elementi deve essere uguale o maggiore di zero.
minItems
Stringa
Specifica il numero minimo di elementi in un array. Gli elementi minimi devono essere uguali o maggiori di zero.

Abilita dati conformi allo schema enablig-schema-compliant-data

Per abilitare tutti i Forms adattivi basati su schema JSON a generare dati conformi allo schema al momento dell’invio del modulo, effettua le seguenti operazioni:

  1. Passa alla console Web Experience Manager all'indirizzo https://server:host/system/console/configMgr.
  2. Individua Configurazione canale web per modulo adattivo e comunicazione interattiva.
  3. Seleziona per aprire la configurazione in modalità di modifica.
  4. Selezionare la casella di controllo Genera dati conformi allo schema.
  5. Salva le impostazioni.

configurazione canale web per modulo adattivo e comunicazione interattiva

Costrutti non supportati non-supported-constructs

Forms adattivo non supporta i seguenti costrutti dello schema JSON:

  • Tipo nullo
  • tipi di unione, come eventuali, e
  • Uno di, uno di, tutti e NON
  • Sono supportati solo array omogenei. Pertanto, il vincolo items deve essere un oggetto e non un array.
  • Riferimenti URI in $ref

Domande frequenti frequently-asked-questions

Perché non è possibile trascinare singoli elementi di una sottomaschera (struttura generata da qualsiasi tipo complesso) per sottomaschere ripetibili (i valori minOccours o maxOccurs sono maggiori di 1)?

In una sottomaschera ripetibile, è necessario utilizzare la sottomaschera completa. Se desideri solo campi selettivi, utilizza l’intera struttura ed elimina quelli indesiderati.

Ho una struttura lunga e complessa in Content Finder. Come trovare un elemento specifico?

Sono disponibili due opzioni:

  • Scorri nella struttura ad albero
  • Utilizzare la casella di ricerca per trovare un elemento

Quale dovrebbe essere l'estensione del file di schema JSON?

L’estensione del file dello schema JSON deve essere .schema.json. Ad esempio, <nomefile>.schema.json.

Consulta anche see-also

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab